From f8345abbc36a40599153fc84e29e2d1e8c6cc0b4 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Tue, 15 Sep 2026 16:28:55 +0200 Subject: [PATCH 01/21] Minor note --- frontend/src/pages/SetupPage.svelte | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/src/pages/SetupPage.svelte b/frontend/src/pages/SetupPage.svelte index 90f3213e..e94cd61b 100644 --- a/frontend/src/pages/SetupPage.svelte +++ b/frontend/src/pages/SetupPage.svelte @@ -170,7 +170,7 @@ -

Enter the token configured by the installation operator.

+

Value of PABAWI_BOOTSTRAP_TOKEN, set by the installation operator in the backend environment.

From 50303e65ba51f21001dd3af24986095636f215b9 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Tue, 15 Sep 2026 23:41:46 +0200 Subject: [PATCH 02/21] Rewrite README for conciseness and add Checkmk integration - Trim verbose sections (TOC, feature list, project structure, long install/config walkthroughs) into tighter prose so the README scans faster and stays easier to maintain. - Document the Checkmk integration alongside existing integrations (CHECKMK_* config, integrations doc link) and add the Entra ID SSO doc link. --- README.md | 246 +++++++++--------------------------------------------- 1 file changed, 41 insertions(+), 205 deletions(-) diff --git a/README.md b/README.md index 2dd5e9e8..26d98c28 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@

Classic Infrastructures Command & Control Awesomeness

-

Pabawi is a web UI for infrastructure management, inventory, and remote execution.
It integrates with Puppet, Bolt, Ansible, PuppetDB, Hiera, SSH, Proxmox, AWS, and Azure providing a single interface for executing commands, browsing inventory, viewing system facts, provisioning VMs, and tracking operations across your entire environment.
Icing on the cake, all the information you see on Pabawi is exposed with an embedded MCP server usable by your favouring AI agents.

+

A web UI for infrastructure management, inventory, and remote execution across Puppet, Bolt, Ansible, PuppetDB, Hiera, SSH, Checkmk, Proxmox, AWS, and Azure. One interface for running commands, browsing inventory and facts, provisioning VMs, and tracking operations. Everything it sees is also exposed through an embedded MCP server for AI agents.

@@ -17,86 +17,33 @@ [![Docker Image](https://img.shields.io/docker/v/example42/pabawi?label=docker&color=2496ed)](https://hub.docker.com/r/example42/pabawi) [![GitHub Stars](https://img.shields.io/github/stars/example42/pabawi?style=social)](https://github.com/example42/pabawi/stargazers) -## Sponsors +Sponsored by AMS-IX - - - -
Pabawi's main sponsor is AMS-IXAMS-IX
+## Who it's for -## Who is this for? - -- **Sysadmins and DevOps teams** using Puppet, Bolt, Ansible, or SSH to manage physical servers and VMs +- **Sysadmins and DevOps teams** managing physical servers and VMs with Puppet, Bolt, Ansible, or SSH - **Puppet Open Source users** who want a web UI without Puppet Enterprise -- **Mixed-tool environments** — if you use both Puppet and Ansible, Pabawi brings them together in one interface +- **Mixed-tool shops** running both Puppet and Ansible, who want one interface instead of two - **Homelabbers** who just want a web frontend for their servers (SSH-only works fine) If you manage "classic infrastructure" — bare metal, VMs, Kubernetes nodes — Pabawi is built for you. -## Table of Contents - -- [Sponsors](#sponsors) -- [Features](#features) -- [Screenshots](#screenshots) -- [Prerequisites](#prerequisites) -- [Installation](#installation) - - [Quick Start](#quick-start) - - [Manual Setup](#manual-setup) - - [Docker](#docker) -- [Upgrading](#upgrading) -- [Configuration](#configuration) -- [Project Structure](#project-structure) -- [Troubleshooting](#troubleshooting) -- [Development and Contributing](#development-and-contributing) -- [Roadmap](#roadmap) -- [License](#license) -- [Support](#support) -- [Acknowledgments](#acknowledgments) - -## Features - -- **Multi-Source Inventory** — nodes from Bolt, PuppetDB, Ansible, SSH, Proxmox, AWS, Azure, with inventory groups -- **Command Execution** — ad-hoc commands on remote nodes with whitelist security -- **Task Execution** — Bolt tasks with automatic parameter discovery -- **Package Management** — install and manage packages across infrastructure -- **Proxmox Provisioning** — VM and container management alongside config management -- **AWS EC2 Provisioning** — cloud instance lifecycle management -- **Azure VM Provisioning** — Azure VM inventory, provisioning, and lifecycle management (start/stop/restart/deallocate) -- **Execution History** — track operations with re-execution capability -- **RBAC Authentication** — role-based access control, multiple users, audit trail -- **MCP Server** — embedded Model Context Protocol server with read-only infrastructure tools for AI assistants -- **Node Facts** — system information from Puppet agents -- **Puppet Reports** — run reports with metrics and resource changes -- **Catalog Inspection** — compiled catalogs, resource relationships, cross-environment diff -- **Event Tracking** — resource changes and failures over time -- **Hiera Data Browser** — hierarchical configuration data and key usage analysis -- **Node Journal** — timeline of events, actions, and notes per node -- **Global Journal** — cross-node timeline with filtering by node, group, event type, source, and date range -- **Real-time Streaming** — live output for command and task execution -- **Expert Mode** — full command lines and debug output -- **Graceful Degradation** — continues operating when individual integrations are unavailable -- **Request Deduplication** — LRU-cached responses for identical API requests to reduce external calls -- **Input Sanitization** — automatic null byte removal, prototype pollution prevention, and deep nesting protection - -## Screenshots - -Pabawi Screenshots +## What it does -Check this [recording](https://asciinema.org/a/1073835) for a sample MCP session. +- **Inventory & facts** from every connected source, merged and deduplicated across integrations +- **Execution** — ad-hoc commands, Bolt tasks, package management, with a security whitelist, live streaming output, and history/re-run +- **Provisioning** — VM/container lifecycle on Proxmox, AWS EC2, and Azure +- **Puppet observability** — reports, catalog inspection with cross-environment diff, resource event tracking, Hiera data browsing +- **Tracking** — per-node and global journal, audit trail, RBAC with multiple users +- **AI-ready** — embedded MCP server exposing inventory, facts, reports, and catalogs read-only to LLM clients -## Prerequisites +See the [Screenshots](docs/screenshots/pabawi-screenshots.png), a sample [MCP session recording](https://asciinema.org/a/1073835), the [User Guide](docs/user-guide.md) for full feature walkthroughs, and [Architecture](docs/architecture.md) for how it's built. -- **Node.js 24 LTS** (see `.nvmrc`) and **npm 11** (or a container engine for Docker deployment) -- **Bolt CLI** — for Bolt integration ([setup](docs/integrations/bolt.md)) -- **Ansible CLI** — for Ansible integration ([setup](docs/integrations/ansible.md)) -- **Puppet/OpenVox agent** — for [PuppetDB](docs/integrations/puppetdb.md) and [Puppetserver](docs/integrations/puppetserver.md) integrations; provides SSL certs -- **Control repo** — for Hiera integration ([setup](docs/integrations/hiera.md)) +## Installing -All integrations are optional — enable only what you use. +Requires **Node.js 24 LTS** and **npm 11** (or a container engine for Docker). Integration CLIs (Bolt, Ansible, Puppet/OpenVox agent) are only needed for the integrations you enable — see [per-integration setup guides](#integrations). -## Installation - -### Quick Start +**Quick start** (interactive setup script — checks prerequisites, generates `backend/.env`, installs dependencies, starts the app): ```bash git clone https://github.com/example42/pabawi @@ -104,167 +51,56 @@ cd pabawi ./scripts/setup.sh ``` -The interactive setup script will: - -1. **Check prerequisites** — Node.js, npm, and optionally Bolt, Ansible, Puppet/OpenVox CLIs -2. **Generate `backend/.env`** — core settings and integrations with smart defaults based on detected tools and SSL certs -3. **Install dependencies** — `npm run install:all` (installs packages and rebuilds native modules with `--ignore-scripts=false`) -4. **Start the application** — development mode, full-stack build, or exit - -### Manual Setup - -First administrator enrollment requires an installation bootstrap token. -See [Initial setup](docs/initial-setup.md) before exposing a fresh installation. +**Manual setup:** ```bash git clone https://github.com/example42/pabawi cd pabawi - -# Install dependencies (rebuilds native modules like bcrypt, sqlite3) -npm run install:all - -# Create your configuration -cp backend/.env.example backend/.env -# Edit backend/.env with your settings - -# Start in development mode -npm run dev:backend # backend on port 3000 -npm run dev:frontend # frontend on port 5173 - -# Or build and serve everything from the backend -npm run dev:fullstack # port 3000 +npm run install:all # installs deps, rebuilds native modules +cp backend/.env.example backend/.env # then edit backend/.env +npm run dev:fullstack # build + serve everything on port 3000 ``` -### Docker +First admin enrollment requires a bootstrap token — see [Initial Setup](docs/initial-setup.md) before exposing a fresh install. + +**Docker:** ```bash -# Create a working directory for persistent data, certs, and project files mkdir pabawi && cd pabawi - -# Create your configuration file (paths are relative to the container) -vi .env - -# Run the image, mounting the current directory -docker run -d \ - --name pabawi \ - --user "$(id -u):1001" \ +vi .env # paths are relative to the container +docker run -d --name pabawi --user "$(id -u):1001" \ -p 127.0.0.1:3000:3000 \ - -v "$(pwd)/pabawi:/pabawi" \ - --env-file ".env" \ + -v "$(pwd)/pabawi:/pabawi" --env-file ".env" \ example42/pabawi:latest ``` -The application starts at . - -For full Docker and Kubernetes deployment instructions, see the [Docker Deployment Guide](docs/deployment/docker.md) and [Kubernetes Guide](docs/deployment/kubernetes.md). - -## Upgrading - -For existing installations, the upgrade path depends on your deployment method: - -| Method | Command | -|---|---| -| Git / source | `git fetch --tags && git checkout v && npm run install:all && npm run build` | -| Docker | `docker pull example42/pabawi:latest` then recreate the container | -| Docker Compose | `docker compose pull && docker compose up -d` | -| Helm / Kubernetes | `helm upgrade pabawi ./charts/pabawi --set image.tag=` | - -Database migrations run automatically on startup. Always back up your database and review the [CHANGELOG](CHANGELOG.md) for breaking changes before upgrading. +Full instructions and Kubernetes/Helm deployment: [Docker Guide](docs/deployment/docker.md), [Kubernetes Guide](docs/deployment/kubernetes.md). -Full instructions: [Upgrade Guide](docs/upgrading.md). +**Upgrading:** `git fetch --tags && git checkout v && npm run install:all && npm run build` (or `docker pull`/`helm upgrade` — see the [Upgrade Guide](docs/upgrading.md)). Migrations run automatically; back up your database first and check the [CHANGELOG](CHANGELOG.md). -## Configuration +## Configuring -All configuration is in `backend/.env`. The setup script generates this file, or use `backend/.env.example` as a template. - -The web UI also includes per-integration setup wizards that generate `.env` snippets you can paste into your configuration file. - -Key configuration areas: +Everything lives in `backend/.env` — generated by the setup script, templated at `backend/.env.example`, or assembled piece by piece from the in-app per-integration setup wizards. All integrations are optional; enable only what you use. | Area | Variables | |---|---| | Core | `PORT`, `HOST`, `LOG_LEVEL` | | Auth | `JWT_SECRET`, `PABAWI_BOOTSTRAP_TOKEN` | -| Bolt | `BOLT_*` | -| PuppetDB / Puppetserver | `PUPPETDB_*`, `PUPPETSERVER_*` | -| Hiera | `HIERA_*` | -| Ansible | `ANSIBLE_*` | -| SSH | `SSH_*` | -| Proxmox | `PROXMOX_*` | -| AWS | `AWS_*` | -| Azure | `AZURE_*` | +| Integrations | `BOLT_*`, `PUPPETDB_*`, `PUPPETSERVER_*`, `HIERA_*`, `ANSIBLE_*`, `SSH_*`, `CHECKMK_*`, `PROXMOX_*`, `AWS_*`, `AZURE_*` | | Security | `COMMAND_WHITELIST*`, `CONCURRENT_EXECUTION_LIMIT` | | MCP | `MCP_ENABLED` | -Full reference: [Configuration Guide](docs/configuration.md). - -## Project Structure - -```text -pabawi/ -├── frontend/ # Svelte 5 + Vite SPA -│ └── src/ -│ ├── components/ # UI components -│ ├── pages/ # Page components -│ └── lib/ # Utilities and rune-based state -├── backend/ # Node.js + Express + TypeScript -│ └── src/ -│ ├── container/ # DI container (ServiceRegistry) -│ ├── plugins/ # Declarative plugin registry -│ ├── integrations/ # Plugin system (Bolt, PuppetDB, SSH, ...) -│ ├── services/ # ExecutionQueue, RBAC, streaming, auth -│ ├── mcp/ # Embedded MCP server and tool handlers -│ ├── routes/ # Express route factories -│ ├── middleware/ # JWT, RBAC, rate limiting, security headers -│ ├── database/ # SQLite / PostgreSQL adapters + migrations -│ ├── errors/ # Typed error classes -│ └── validation/ # Zod request schemas -├── docs/ # Documentation -│ ├── integrations/ # Per-integration setup guides -│ └── deployment/ # Docker and Kubernetes guides -├── e2e/ # Playwright E2E tests -└── package.json # Root workspace configuration -``` - -See [Architecture](docs/architecture.md) for a detailed description of the plugin system and data flows. - -## Troubleshooting - -See the [Troubleshooting Guide](docs/troubleshooting.md) for common issues with installation, configuration, and integrations. - -## Development and Contributing - -See the [Development Guide](docs/development.md) for setup, testing, and contribution guidelines. - - -### Version History - -See [CHANGELOG](CHANGELOG.md). - - -## License - -Apache License 2.0 — see [LICENSE](LICENSE). - -## Support - -**Documentation** - -- [Architecture](docs/architecture.md) | [Configuration](docs/configuration.md) | [User Guide](docs/user-guide.md) | [API Reference](docs/api.md) -- [Permissions & RBAC](docs/permissions-rbac.md) | [MCP Server](docs/mcp.md) | [Upgrading](docs/upgrading.md) | [Troubleshooting](docs/troubleshooting.md) | [Development](docs/development.md) - -**Integrations** - -- [Bolt](docs/integrations/bolt.md) | [Ansible](docs/integrations/ansible.md) | [SSH](docs/integrations/ssh.md) -- [PuppetDB](docs/integrations/puppetdb.md) | [Puppetserver](docs/integrations/puppetserver.md) | [Hiera](docs/integrations/hiera.md) -- [Proxmox](docs/integrations/proxmox.md) | [AWS](docs/integrations/aws.md) | [Azure](docs/integrations/azure.md) - -**Deployment** +Full reference: [Configuration Guide](docs/configuration.md). Architecture and code layout: [Architecture](docs/architecture.md). -- [Docker](docs/deployment/docker.md) | [Kubernetes](docs/deployment/kubernetes.md) +### Integrations -For help: enable expert mode for diagnostics, or [open a GitHub issue](https://github.com/example42/pabawi/issues) with version info, sanitized config, reproduction steps, and error messages. +[Bolt](docs/integrations/bolt.md) · [Ansible](docs/integrations/ansible.md) · [SSH](docs/integrations/ssh.md) · [PuppetDB](docs/integrations/puppetdb.md) · [Puppetserver](docs/integrations/puppetserver.md) · [Hiera](docs/integrations/hiera.md) · [Checkmk](docs/integrations/checkmk.md) · [Proxmox](docs/integrations/proxmox.md) · [AWS](docs/integrations/aws.md) · [Azure](docs/integrations/azure.md) · [Entra ID SSO](docs/integrations/entra-id.md) -## Acknowledgments +## The usuals -Pabawi builds on: [Puppet/OpenVox](https://puppet.com), [Bolt](https://puppet.com/docs/bolt), [PuppetDB](https://puppet.com/docs/puppetdb), [Svelte 5](https://svelte.dev), [Node.js](https://nodejs.org), [TypeScript](https://www.typescriptlang.org), [SQLite](https://sqlite.org), [PostgreSQL](https://www.postgresql.org). Thanks to all contributors and the Puppet community. +- **Documentation:** [User Guide](docs/user-guide.md) · [Architecture](docs/architecture.md) · [API Reference](docs/api.md) · [Permissions & RBAC](docs/permissions-rbac.md) · [MCP Server](docs/mcp.md) +- **Troubleshooting:** [Troubleshooting Guide](docs/troubleshooting.md) — for help beyond that, enable expert mode for diagnostics and [open a GitHub issue](https://github.com/example42/pabawi/issues) with version info, sanitized config, and reproduction steps +- **Development & contributing:** [Development Guide](docs/development.md) +- **Version history:** [CHANGELOG](CHANGELOG.md) +- **License:** [Apache License 2.0](LICENSE) +- **Built on:** [Puppet/OpenVox](https://puppet.com), [Bolt](https://puppet.com/docs/bolt), [PuppetDB](https://puppet.com/docs/puppetdb), [Svelte 5](https://svelte.dev), [Node.js](https://nodejs.org), [TypeScript](https://www.typescriptlang.org), [SQLite](https://sqlite.org), [PostgreSQL](https://www.postgresql.org), and the Puppet community From d5b4eb04078cc9df443e9a874594367766d765b8 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Wed, 16 Sep 2026 22:25:59 +0200 Subject: [PATCH 03/21] feat(docker): publish core and batteries images --- .github/workflows/ci.yml | 33 ++++-- .github/workflows/publish.yml | 62 +++++++---- CHANGELOG.md | 24 +++++ Dockerfile | 66 +++++++++--- Dockerfile.alpine | 2 +- Dockerfile.ubuntu | 2 +- README.md | 6 +- backend/package.json | 2 +- backend/src/server.ts | 2 +- charts/pabawi/Chart.yaml | 4 +- charts/pabawi/values.yaml | 2 + docker-compose.yml | 3 +- docs/deployment/docker.md | 23 +++- docs/deployment/supply-chain.md | 52 +++++---- docs/internal/dockerhub.md | 8 ++ docs/openapi.yaml | 2 +- docs/upgrading.md | 6 +- frontend/package.json | 2 +- frontend/src/components/Navigation.svelte | 2 +- package-lock.json | 8 +- package.json | 2 +- scripts/deployment/docker-images.test.mjs | 100 ++++++++++++++++++ scripts/docker-build-multiarch.sh | 24 ++++- scripts/docker-run.ps1 | 2 +- scripts/docker-run.sh | 2 +- scripts/documentation/contracts.test.mjs | 18 ++++ scripts/setup.sh | 4 +- scripts/supply-chain/image-smoke.sh | 39 ++++++- scripts/supply-chain/scan-image.sh | 10 +- .../supply-chain/trivy-batteries-ignore.yaml | 11 ++ 30 files changed, 429 insertions(+), 94 deletions(-) create mode 100644 scripts/deployment/docker-images.test.mjs create mode 100644 scripts/supply-chain/trivy-batteries-ignore.yaml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5965c71e..feff1660 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,6 +31,9 @@ jobs: - name: Check documentation contracts run: node --test scripts/documentation/contracts.test.mjs + - name: Check Docker image contracts + run: node --test scripts/deployment/docker-images.test.mjs + - name: Run ESLint run: npm run lint @@ -140,25 +143,41 @@ jobs: strategy: fail-fast: false matrix: - variant: [bookworm, alpine, ubuntu] + include: + - variant: bookworm-core + file: Dockerfile + target: core + profile: core + - variant: bookworm-batteries + file: Dockerfile + target: batteries + profile: batteries + - variant: alpine + file: Dockerfile.alpine + target: "" + profile: bolt + - variant: ubuntu + file: Dockerfile.ubuntu + target: "" + profile: bolt steps: - uses: actions/checkout@v4 - uses: docker/setup-buildx-action@v3 - name: Build and verify shipped image run: | - file=Dockerfile - if [ "${{ matrix.variant }}" != bookworm ]; then file="Dockerfile.${{ matrix.variant }}"; fi - docker build --no-cache -f "$file" -t pabawi:test . - bash scripts/supply-chain/image-smoke.sh pabawi:test + target=() + if [ -n "${{ matrix.target }}" ]; then target=(--target "${{ matrix.target }}"); fi + docker build --no-cache "${target[@]}" -f "${{ matrix.file }}" -t pabawi:test . + bash scripts/supply-chain/image-smoke.sh pabawi:test "${{ matrix.profile }}" mkdir -p artifacts docker run --rm -i --entrypoint node pabawi:test < scripts/supply-chain/dependency-graph.cjs > artifacts/dependencies.json - docker build --no-cache --target backend-deps -f "$file" -t pabawi:deps-repeat . + docker build --no-cache --target backend-deps -f "${{ matrix.file }}" -t pabawi:deps-repeat . docker run --rm -i --entrypoint node pabawi:deps-repeat < scripts/supply-chain/dependency-graph.cjs > artifacts/dependencies-repeat.json cmp artifacts/dependencies.json artifacts/dependencies-repeat.json if [ "${{ matrix.variant }}" = ubuntu ]; then docker run --rm --entrypoint ruby pabawi:test /opt/bolt/test-winrm-rubyzip.rb docker run --rm -i --entrypoint ruby pabawi:test < docker/bolt/dependency-graph.rb > artifacts/ruby-dependencies.json - docker build --no-cache --target bolt-builder -f "$file" -t pabawi:ruby-repeat . + docker build --no-cache --target bolt-builder -f "${{ matrix.file }}" -t pabawi:ruby-repeat . docker run --rm -i --entrypoint ruby pabawi:ruby-repeat < docker/bolt/dependency-graph.rb > artifacts/ruby-dependencies-repeat.json cmp artifacts/ruby-dependencies.json artifacts/ruby-dependencies-repeat.json fi diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index ba534ec3..c2456cef 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -8,6 +8,7 @@ on: env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }} + DOCKERHUB_IMAGE: example42/pabawi concurrency: group: publish-${{ github.ref }} @@ -20,6 +21,7 @@ jobs: fail-fast: false matrix: arch: [amd64, arm64] + profile: [core, batteries] permissions: contents: read packages: write @@ -40,40 +42,55 @@ jobs: with: context: . platforms: linux/${{ matrix.arch }} + target: ${{ matrix.profile }} load: true push: false tags: pabawi:candidate labels: ${{ steps.meta.outputs.labels }} - cache-from: type=gha,scope=release-${{ matrix.arch }} - cache-to: type=gha,mode=max,scope=release-${{ matrix.arch }} + cache-from: type=gha,scope=release-${{ matrix.profile }}-${{ matrix.arch }} + cache-to: type=gha,mode=max,scope=release-${{ matrix.profile }}-${{ matrix.arch }} - name: Verify release candidate env: DOCKER_DEFAULT_PLATFORM: linux/${{ matrix.arch }} run: | - bash scripts/supply-chain/image-smoke.sh pabawi:candidate + bash scripts/supply-chain/image-smoke.sh pabawi:candidate ${{ matrix.profile }} mkdir -p artifacts docker run --rm -i --entrypoint node pabawi:candidate < scripts/supply-chain/dependency-graph.cjs > artifacts/dependencies.json - name: Scan release candidate - continue-on-error: true - run: bash scripts/supply-chain/scan-image.sh pabawi:candidate artifacts + run: | + ignore_file=() + if [[ "${{ matrix.profile }}" = batteries ]]; then + ignore_file=(scripts/supply-chain/trivy-batteries-ignore.yaml) + fi + bash scripts/supply-chain/scan-image.sh pabawi:candidate artifacts "${ignore_file[@]}" - name: Retain release evidence if: always() uses: actions/upload-artifact@v4 with: - name: release-evidence-${{ matrix.arch }} + name: release-evidence-${{ matrix.profile }}-${{ matrix.arch }} path: artifacts/*.json - uses: docker/login-action@v3 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - - name: Push the verified image without rebuilding + - uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Push the verified image to both registries without rebuilding id: push run: | - tag="${REGISTRY}/${IMAGE_NAME}:${GITHUB_REF_NAME}-${{ matrix.arch }}" - docker tag pabawi:candidate "$tag" - docker push "$tag" - digest=$(docker inspect --format '{{index .RepoDigests 0}}' "$tag") + suffix="" + if [[ "${{ matrix.profile }}" = batteries ]]; then suffix="-batteries"; fi + architecture_tag="${GITHUB_REF_NAME}${suffix}-${{ matrix.arch }}" + ghcr_tag="${REGISTRY}/${IMAGE_NAME}:${architecture_tag}" + dockerhub_tag="${DOCKERHUB_IMAGE}:${architecture_tag}" + docker tag pabawi:candidate "$ghcr_tag" + docker tag pabawi:candidate "$dockerhub_tag" + docker push "$ghcr_tag" + docker push "$dockerhub_tag" + digest=$(docker inspect --format '{{index .RepoDigests 0}}' "$ghcr_tag") echo "digest=${digest#*@}" >> "$GITHUB_OUTPUT" - name: Attest the verified image uses: actions/attest-build-provenance@v1 @@ -94,16 +111,25 @@ jobs: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} + - uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Publish verified architecture images run: | version="${GITHUB_REF_NAME#v}" - image="${REGISTRY}/${IMAGE_NAME}" - tags=(--tag "$image:$version" --tag "$image:sha-${GITHUB_SHA:0:7}") - if [[ "$version" != *-* ]]; then - tags+=(--tag "$image:${version%.*}" --tag "$image:${version%%.*}" --tag "$image:latest") - fi - docker buildx imagetools create "${tags[@]}" \ - "$image:${GITHUB_REF_NAME}-amd64" "$image:${GITHUB_REF_NAME}-arm64" + for image in "${REGISTRY}/${IMAGE_NAME}" "${DOCKERHUB_IMAGE}"; do + core_tags=(--tag "$image:$version" --tag "$image:sha-${GITHUB_SHA:0:7}") + batteries_tags=(--tag "$image:batteries-$version" --tag "$image:batteries-sha-${GITHUB_SHA:0:7}") + if [[ "$version" != *-* ]]; then + core_tags+=(--tag "$image:${version%.*}" --tag "$image:${version%%.*}" --tag "$image:latest") + batteries_tags+=(--tag "$image:batteries-${version%.*}" --tag "$image:batteries-${version%%.*}" --tag "$image:batteries") + fi + docker buildx imagetools create "${core_tags[@]}" \ + "$image:${GITHUB_REF_NAME}-amd64" "$image:${GITHUB_REF_NAME}-arm64" + docker buildx imagetools create "${batteries_tags[@]}" \ + "$image:${GITHUB_REF_NAME}-batteries-amd64" "$image:${GITHUB_REF_NAME}-batteries-arm64" + done create-release: needs: publish-manifest diff --git a/CHANGELOG.md b/CHANGELOG.md index 3be0d68f..2e84a2e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,29 @@ # Changelog +## [1.5.1] - 2026-09-16 + +### Container images + +- `example42/pabawi` and `ghcr.io/example42/pabawi` now publish a minimal core + image as the default tag family. The core image contains Pabawi but excludes + Bolt, Ansible, Puppet/OpenVox, OpenSSH and the other integration CLIs. +- A batteries image adds Bolt 5.6.0, Ansible 2.14.18, Puppet/OpenVox 8.29.0, + Facter 5.6.1, OpenSSH, Git, curl, rsync and sshpass. It is published under + `batteries`, `batteries-1`, `batteries-1.5`, `batteries-1.5.1` and immutable + commit tags. +- Release CI builds and smoke-tests both profiles for amd64 and arm64, then + publishes the verified images to Docker Hub and GHCR without rebuilding. + Compose, setup and convenience scripts select the batteries image where the + integration toolchain is expected. + +### Security + +- Core and batteries images retain SBOM and vulnerability evidence. Fixable + high or critical findings block publishing, except for a reviewed + batteries-only exception for `CVE-2026-85396` in `rubyzip` 2.4.1. OpenBolt's + current `winrm-fs` dependency prevents a compatible upgrade. The exception + is scoped to the exact gem path and package URL and expires on 2026-12-31. + ## [1.5.0] - 2026-09-14 ### Security: breaking for operators diff --git a/Dockerfile b/Dockerfile index 99d42992..08372b74 100644 --- a/Dockerfile +++ b/Dockerfile @@ -26,8 +26,9 @@ RUN npm ci --workspace=backend --omit=dev --ignore-scripts --no-audit --no-fund # Keep both hoisted and workspace-local packages in their locked locations. RUN mkdir -p backend/node_modules -# Stage 3: Install OpenBolt from OpenVox upstream packages -FROM node:24.21.0-bookworm-slim@sha256:2fe369e969550cde8e867afc3fe370b260140cab4a23d467074295b42163d553 AS bolt-builder +# Stage 3: Build the optional infrastructure toolchain. The default core +# target does not depend on this stage, so BuildKit skips it entirely. +FROM node:24.21.0-bookworm-slim@sha256:2fe369e969550cde8e867afc3fe370b260140cab4a23d467074295b42163d553 AS toolchain-builder # hadolint ignore=DL3008 RUN apt-get update && \ @@ -39,7 +40,9 @@ RUN apt-get update && \ && dpkg -i openvox8-release-debian12.deb \ && rm openvox8-release-debian12.deb \ && apt-get update \ - && apt-get install -y --no-install-recommends openbolt=5.6.0-1+debian12 \ + && apt-get install -y --no-install-recommends \ + openbolt=5.6.0-1+debian12 \ + openvox-agent=8.29.0-1+debian12 \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* @@ -58,34 +61,36 @@ RUN apt-get update && \ faraday:2.14.3 \ jwt:2.10.3 \ resolv:0.7.2 \ + && /opt/puppetlabs/puppet/bin/gem install --no-document resolv:0.7.2 \ && /opt/puppetlabs/bolt/bin/gem uninstall --force --ignore-dependencies \ concurrent-ruby:1.3.6 faraday:2.14.2 jwt:2.10.2 \ && rm -rf /opt/puppetlabs/bolt/lib/ruby/gems/3.2.0/specifications/default/resolv-0.2.3.gemspec \ /opt/puppetlabs/bolt/lib/ruby/gems/3.2.0/gems/resolv-0.2.3 \ + /opt/puppetlabs/puppet/lib/ruby/gems/3.2.0/specifications/default/resolv-0.2.3.gemspec \ + /opt/puppetlabs/puppet/lib/ruby/gems/3.2.0/gems/resolv-0.2.3 \ && apt-get purge -y make gcc libc6-dev && apt-get autoremove -y \ && rm -rf /var/lib/apt/lists/* -# Stage 4: Production image -FROM node:24.21.0-bookworm-slim@sha256:2fe369e969550cde8e867afc3fe370b260140cab4a23d467074295b42163d553 +# Stage 4: Core production image. This is the default published image and +# contains only Pabawi and the operating-system packages it needs to start. +FROM node:24.21.0-bookworm-slim@sha256:2fe369e969550cde8e867afc3fe370b260140cab4a23d467074295b42163d553 AS core ARG TARGETPLATFORM ARG BUILDPLATFORM # Add metadata labels -LABEL org.opencontainers.image.title="Pabawi" -LABEL org.opencontainers.image.description="Puppet Ansible Bolt Awesome Web Interface" -LABEL org.opencontainers.image.version="1.5.0" +LABEL org.opencontainers.image.title="Pabawi Core" +LABEL org.opencontainers.image.description="Pabawi infrastructure management web interface" +LABEL org.opencontainers.image.version="1.5.1" LABEL org.opencontainers.image.vendor="example42" LABEL org.opencontainers.image.source="https://github.com/example42/pabawi" -# Install only runtime dependencies +# Install only core runtime dependencies. Integration CLIs belong in the +# batteries target below. # hadolint ignore=DL3008 RUN apt-get update && \ apt-get install -y --no-install-recommends \ bash \ - openssh-client \ - git \ - coreutils \ - ansible \ + ca-certificates \ && apt-get install -y --only-upgrade libpcre2-8-0 \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* @@ -95,10 +100,6 @@ RUN apt-get update && \ # dependencies (e.g. brace-expansion, tar, ip-address) don't ship either. RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack -# Copy Bolt installation from upstream package builder stage -COPY --from=bolt-builder /opt/puppetlabs /opt/puppetlabs -RUN ln -s /opt/puppetlabs/bolt/bin/bolt /usr/local/bin/bolt - # Create non-root user RUN groupadd -g 1001 pabawi && \ useradd -u 1001 -g pabawi -m -s /bin/bash pabawi @@ -168,3 +169,34 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \ # Start the application CMD ["node", "dist/server.js"] + +# Stage 5: Optional batteries-included image. It adds every local CLI invoked +# by an integration plus the Puppet/OpenVox operator toolchain. Cloud and API +# integrations use the Node SDKs already present in the core image. +FROM core AS batteries +USER root + +# hadolint ignore=DL3008 +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + ansible \ + curl \ + git \ + openssh-client \ + rsync \ + sshpass \ + && apt-get clean \ + && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* + +COPY --from=toolchain-builder /opt/puppetlabs /opt/puppetlabs +RUN ln -s /opt/puppetlabs/bolt/bin/bolt /usr/local/bin/bolt \ + && ln -s /opt/puppetlabs/puppet/bin/facter /usr/local/bin/facter \ + && ln -s /opt/puppetlabs/puppet/bin/puppet /usr/local/bin/puppet + +LABEL org.opencontainers.image.title="Pabawi Batteries Included" +LABEL org.opencontainers.image.description="Pabawi with Bolt, Ansible, Puppet/OpenVox, and SSH tooling" + +USER pabawi + +# Keep the default Dockerfile result backward-compatible with the core image. +FROM core AS final diff --git a/Dockerfile.alpine b/Dockerfile.alpine index f8302ae5..0b28dbad 100644 --- a/Dockerfile.alpine +++ b/Dockerfile.alpine @@ -45,7 +45,7 @@ ARG BUILDPLATFORM # Add metadata labels LABEL org.opencontainers.image.title="Pabawi" LABEL org.opencontainers.image.description="Puppet Ansible Bolt Awesome Web Interface" -LABEL org.opencontainers.image.version="1.5.0" +LABEL org.opencontainers.image.version="1.5.1" LABEL org.opencontainers.image.vendor="example42" LABEL org.opencontainers.image.source="https://github.com/example42/pabawi" diff --git a/Dockerfile.ubuntu b/Dockerfile.ubuntu index b4d3fb93..922ab09a 100644 --- a/Dockerfile.ubuntu +++ b/Dockerfile.ubuntu @@ -54,7 +54,7 @@ ARG BUILDPLATFORM # Add metadata labels LABEL org.opencontainers.image.title="Pabawi" LABEL org.opencontainers.image.description="Puppet Ansible Bolt Awesome Web Interface" -LABEL org.opencontainers.image.version="1.5.0" +LABEL org.opencontainers.image.version="1.5.1" LABEL org.opencontainers.image.vendor="example42" LABEL org.opencontainers.image.source="https://github.com/example42/pabawi" diff --git a/README.md b/README.md index 26d98c28..eef9c6e7 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ npm run dev:fullstack # build + serve everything on port 3000 First admin enrollment requires a bootstrap token — see [Initial Setup](docs/initial-setup.md) before exposing a fresh install. -**Docker:** +**Docker (core image):** ```bash mkdir pabawi && cd pabawi @@ -74,6 +74,10 @@ docker run -d --name pabawi --user "$(id -u):1001" \ example42/pabawi:latest ``` +The core image contains the Pabawi application only. Use +`example42/pabawi:batteries` when Bolt, Ansible, Puppet/OpenVox, or OpenSSH +commands must run inside the container. + Full instructions and Kubernetes/Helm deployment: [Docker Guide](docs/deployment/docker.md), [Kubernetes Guide](docs/deployment/kubernetes.md). **Upgrading:** `git fetch --tags && git checkout v && npm run install:all && npm run build` (or `docker pull`/`helm upgrade` — see the [Upgrade Guide](docs/upgrading.md)). Migrations run automatically; back up your database first and check the [CHANGELOG](CHANGELOG.md). diff --git a/backend/package.json b/backend/package.json index 4d74cd52..3d08be63 100644 --- a/backend/package.json +++ b/backend/package.json @@ -1,6 +1,6 @@ { "name": "backend", - "version": "1.5.0", + "version": "1.5.1", "description": "Backend API server for Pabawi", "main": "dist/server.js", "scripts": { diff --git a/backend/src/server.ts b/backend/src/server.ts index d55ecc7e..170c08c2 100644 --- a/backend/src/server.ts +++ b/backend/src/server.ts @@ -600,7 +600,7 @@ async function startServer(): Promise { res.status(overall === "ok" ? 200 : 503).json({ status: overall, message: "Backend API is running", - version: "1.5.0", + version: "1.5.1", checks: { database: dbError ? { status: dbStatus, error: dbError } : { status: dbStatus }, }, diff --git a/charts/pabawi/Chart.yaml b/charts/pabawi/Chart.yaml index 28a1cb26..d245a357 100644 --- a/charts/pabawi/Chart.yaml +++ b/charts/pabawi/Chart.yaml @@ -2,8 +2,8 @@ apiVersion: v2 name: pabawi description: Pabawi infrastructure management web UI type: application -version: 0.2.0 -appVersion: "1.5.0" +version: 0.2.1 +appVersion: "1.5.1" home: https://github.com/example42/pabawi sources: - https://github.com/example42/pabawi diff --git a/charts/pabawi/values.yaml b/charts/pabawi/values.yaml index daae6211..40af9341 100644 --- a/charts/pabawi/values.yaml +++ b/charts/pabawi/values.yaml @@ -6,6 +6,8 @@ revisionHistoryLimit: 10 image: repository: example42/pabawi pullPolicy: IfNotPresent + # Use batteries- when Bolt, Ansible, Puppet/OpenVox, or OpenSSH + # commands must run inside the pod. tag: "" imagePullSecrets: [] diff --git a/docker-compose.yml b/docker-compose.yml index 24ea002c..a047a9db 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,7 @@ services: app: - image: example42/pabawi:latest + # This example mounts Bolt and Ansible projects, so it uses the toolchain image. + image: example42/pabawi:batteries container_name: pabawi env_file: - .env diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index 131ecd98..f78b05d8 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -7,7 +7,7 @@ Before starting a fresh container, configure `JWT_SECRET` and an independent [Initial setup](../initial-setup.md) to claim the administrator account. ```bash -# Using published image +# Using the batteries image because this example mounts a Bolt project docker run -d \ --name pabawi \ --user "$(id -u):1001" \ @@ -15,9 +15,20 @@ docker run -d \ -v "$(pwd)/bolt-project:/opt/pabawi/bolt-project:ro" \ -v "$(pwd)/data:/opt/pabawi/data" \ --env-file .env \ - example42/pabawi:latest + example42/pabawi:batteries ``` +Two image profiles are published from the same source and version: + +| Tag | Contents | Use when | +|---|---|---| +| `example42/pabawi:latest` | Pabawi application and Node dependencies | Integrations use HTTP APIs, cloud SDKs, or the embedded SSH client | +| `example42/pabawi:batteries` | Core plus Bolt, Ansible, Puppet/OpenVox, OpenSSH, Git, rsync, and sshpass | Integrations need local infrastructure commands | + +Versioned core tags use ``, `.`, and ``. The full +image uses `batteries-`, `batteries-.`, and +`batteries-`. Pre-releases receive only their exact version tags. + `--user "$(id -u):1001"`: your user must be able to read all mounted files. Run build and repository Compose examples from the repository root. Standalone @@ -34,13 +45,15 @@ See [Docker port binding](https://docs.docker.com/reference/compose-file/service ```bash docker build -t pabawi:latest . -docker build -f Dockerfile.alpine -t pabawi:alpine . # smaller +docker build --target core -t pabawi:core . +docker build --target batteries -t pabawi:batteries . ``` **Multi-arch:** ```bash -docker buildx build --platform linux/amd64,linux/arm64 -t pabawi:latest . +docker buildx build --platform linux/amd64,linux/arm64 --target core -t pabawi:core . +docker buildx build --platform linux/amd64,linux/arm64 --target batteries -t pabawi:batteries . ``` ## Volume Mounts @@ -69,7 +82,7 @@ chmod 600 ./certs/*.pem ./certs/*.key ```yaml services: pabawi: - image: example42/pabawi:latest + image: example42/pabawi:batteries restart: unless-stopped ports: - "127.0.0.1:3000:3000" diff --git a/docs/deployment/supply-chain.md b/docs/deployment/supply-chain.md index 420c14a6..54879987 100644 --- a/docs/deployment/supply-chain.md +++ b/docs/deployment/supply-chain.md @@ -38,30 +38,44 @@ From the repository root: ```bash node --test scripts/supply-chain/install-approved.test.mjs -docker build -t pabawi:verify . -bash scripts/supply-chain/image-smoke.sh pabawi:verify -docker run --rm -i --entrypoint node pabawi:verify < scripts/supply-chain/dependency-graph.cjs > dependencies.json -bash scripts/supply-chain/scan-image.sh pabawi:verify /tmp/pabawi-image-evidence +docker build --target core -t pabawi:core-verify . +bash scripts/supply-chain/image-smoke.sh pabawi:core-verify core +docker build --target batteries -t pabawi:batteries-verify . +bash scripts/supply-chain/image-smoke.sh pabawi:batteries-verify batteries +docker run --rm -i --entrypoint node pabawi:core-verify < scripts/supply-chain/dependency-graph.cjs > dependencies.json +bash scripts/supply-chain/scan-image.sh pabawi:core-verify /tmp/pabawi-core-image-evidence +bash scripts/supply-chain/scan-image.sh pabawi:batteries-verify /tmp/pabawi-batteries-image-evidence scripts/supply-chain/trivy-batteries-ignore.yaml ``` -Repeat with `-f Dockerfile.alpine` and `-f Dockerfile.ubuntu` and distinct tags. +Build the alternative Dockerfiles with distinct tags and run the smoke script +with the `bolt` profile. The smoke test checks the non-root Node runtime, bcrypt, an actual SQLite query, -SSH module loading, Bolt task discovery, migrations, HTTP health, frontend delivery -and denial of anonymous inventory requests. It uses disposable container storage -and does not dispatch infrastructure commands. +SSH module loading, migrations, HTTP health, frontend delivery and denial of +anonymous inventory requests. The core profile also proves that integration CLIs +are absent. The batteries profile checks Bolt task discovery and the Bolt, +Ansible, Puppet/OpenVox and OpenSSH commands. It uses disposable container +storage and does not dispatch infrastructure commands. -CI builds all three variants, then performs a second uncached production -installation and compares its dependency graph with the shipped image. The graph -check validates installed versions against the lockfile and root security overrides. -Release CI smoke-tests each architecture, scans the locally exported image, and -pushes that same image without rebuilding. The multi-architecture manifest is -published only after both architecture jobs succeed. +CI builds core and batteries targets plus the Alpine and Ubuntu alternatives, +then performs a second uncached production installation and compares its +dependency graph with each image. The graph check validates installed versions +against the lockfile and root security overrides. Release CI smoke-tests both +profiles on each architecture, scans the locally exported images, and pushes +those same images to Docker Hub and GHCR without rebuilding. Both +multi-architecture manifests are published only after all four architecture +and profile jobs succeed. GitHub Actions requires `DOCKERHUB_USERNAME` and +`DOCKERHUB_TOKEN` repository secrets. The pinned Trivy scanner produces `sbom.cdx.json` and `vulnerabilities.json` from the exported image archive. It scans OS, Ruby, Python, Java and JavaScript packages, including the embedded frontend SBOM. The image digest and dependency inventory -are retained with the reports. High or critical advisories fail the release gate, -including findings without an available fix. Scanner errors also fail the gate. +are retained with the reports. Fixable high or critical advisories fail the +release gate. Scanner errors also fail the gate. The batteries image has one +scoped, expiring exception for `CVE-2026-85396` in its bundled `rubyzip` 2.4.1. +OpenBolt 5.6.0 depends on `winrm-fs` 1.3.5, which constrains rubyzip to the +vulnerable 2.x line. The exception matches that exact package URL and gemspec +path, applies only to the batteries profile, and expires on 2026-12-31. The +unfiltered JSON report still records the finding. See [Trivy's SBOM documentation](https://github.com/aquasecurity/trivy/blob/main/docs/guide/supply-chain/sbom.md). ## Triage and reproducibility limits @@ -69,9 +83,9 @@ See [Trivy's SBOM documentation](https://github.com/aquasecurity/trivy/blob/main The release maintainer owns scan triage with the security maintainer. For each finding, record the artifact digest, advisory, installed and fixed versions, reachability assessment, remediation owner and disposition. Do not equate an -unreachable-looking dependency with an approved exception. No advisory suppressions -are configured. A blocked gate requires remediation or a separately reviewed, -scoped and expiring exception before release. +unreachable-looking dependency with an approved exception. A blocked gate +requires remediation or a separately reviewed, scoped and expiring exception +before release. The npm graph and base-image inputs are pinned. Distribution packages still come from live signed repositories, and the Alpine OpenBolt gem dependency tree is resolved by RubyGems. diff --git a/docs/internal/dockerhub.md b/docs/internal/dockerhub.md index ffa36d57..0179766f 100644 --- a/docs/internal/dockerhub.md +++ b/docs/internal/dockerhub.md @@ -44,6 +44,14 @@ docker run -d \ example42/pabawi:latest ``` +This is the core image. It intentionally excludes Bolt, Ansible, Puppet/OpenVox, +OpenSSH, Git, rsync, and sshpass. For local integration commands, use the +batteries-included image instead: + +```bash +docker run --rm example42/pabawi:batteries +``` + Access the UI at ## Documentation diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 830f7e2d..0b4122fd 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -41,7 +41,7 @@ info: enabled sources. Subscribe to `/journal/global/stream` for a live SSE feed, or query `/journal/{nodeId}` for a node's history. - version: 1.5.0 + version: 1.5.1 contact: name: Pabawi Support url: https://pabawi.example42.com diff --git a/docs/upgrading.md b/docs/upgrading.md index d360b678..e1cbd317 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -124,9 +124,9 @@ For production, pin to tags. ```bash # 1. Pull the new image -docker pull example42/pabawi:latest +docker pull example42/pabawi:batteries # or a specific version: -# docker pull example42/pabawi:1.4.0 +# docker pull example42/pabawi:batteries-1.4.0 # 2. Stop and remove the old container docker stop pabawi @@ -142,7 +142,7 @@ docker run -d \ -v "$(pwd)/data:/opt/pabawi/data" \ -v "$(pwd)/bolt-project:/opt/pabawi/bolt-project:ro" \ --env-file .env \ - example42/pabawi:latest + example42/pabawi:batteries ``` Your data persists in the mounted volumes. The new container applies any diff --git a/frontend/package.json b/frontend/package.json index 08bbbb28..94fa1520 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "frontend", - "version": "1.5.0", + "version": "1.5.1", "description": "Pabawi frontend web interface", "type": "module", "scripts": { diff --git a/frontend/src/components/Navigation.svelte b/frontend/src/components/Navigation.svelte index 3e401d39..dad9e178 100644 --- a/frontend/src/components/Navigation.svelte +++ b/frontend/src/components/Navigation.svelte @@ -148,7 +148,7 @@

Pabawi

- v1.5.0 + v1.5.1
diff --git a/package-lock.json b/package-lock.json index 941b4f53..fc10efb4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "pabawi", - "version": "1.5.0", + "version": "1.5.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "pabawi", - "version": "1.5.0", + "version": "1.5.1", "license": "Apache-2.0", "workspaces": [ "frontend", @@ -29,7 +29,7 @@ } }, "backend": { - "version": "1.5.0", + "version": "1.5.1", "dependencies": { "@aws-sdk/client-ec2": "^3.700.0", "@aws-sdk/client-sts": "^3.700.0", @@ -84,7 +84,7 @@ } }, "frontend": { - "version": "1.5.0", + "version": "1.5.1", "dependencies": { "@novnc/novnc": "^1.7.0", "@xterm/addon-attach": "^0.12.0", diff --git a/package.json b/package.json index 9d40d658..3832f28c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pabawi", - "version": "1.5.0", + "version": "1.5.1", "description": "Pabawi - Web interface for Bolt automation tool", "private": true, "workspaces": [ diff --git a/scripts/deployment/docker-images.test.mjs b/scripts/deployment/docker-images.test.mjs new file mode 100644 index 00000000..97ab3f69 --- /dev/null +++ b/scripts/deployment/docker-images.test.mjs @@ -0,0 +1,100 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import test from "node:test"; + +const dockerfile = readFileSync(new URL("../../Dockerfile", import.meta.url), "utf8"); +const publishWorkflow = readFileSync( + new URL("../../.github/workflows/publish.yml", import.meta.url), + "utf8", +); +const smokeTest = readFileSync( + new URL("../supply-chain/image-smoke.sh", import.meta.url), + "utf8", +); +const scanScript = readFileSync( + new URL("../supply-chain/scan-image.sh", import.meta.url), + "utf8", +); +const batteriesIgnore = readFileSync( + new URL("../supply-chain/trivy-batteries-ignore.yaml", import.meta.url), + "utf8", +); + +test("the default image resolves to the core target", () => { + const core = dockerfile.indexOf(" AS core\n"); + const batteries = dockerfile.indexOf("FROM core AS batteries"); + const final = dockerfile.indexOf("FROM core AS final"); + + assert.ok(core >= 0, "missing core target"); + assert.ok(batteries > core, "batteries must extend core"); + assert.ok(final > batteries, "the final default stage must follow batteries"); + assert.equal(dockerfile.slice(final).trim(), "FROM core AS final"); +}); + +test("the batteries target contains the integration command toolchain", () => { + const batteries = dockerfile.slice(dockerfile.indexOf("FROM core AS batteries")); + + for (const command of [ + "ansible", + "curl", + "git", + "openssh-client", + "rsync", + "sshpass", + "/usr/local/bin/bolt", + "/usr/local/bin/facter", + "/usr/local/bin/puppet", + ]) { + assert.match(batteries, new RegExp(command.replaceAll("/", "\\/"))); + } +}); + +test("release CI builds and publishes both profiles", () => { + assert.match(publishWorkflow, /profile: \[core, batteries\]/); + assert.match(publishWorkflow, /target: \$\{\{ matrix\.profile \}\}/); + assert.match(publishWorkflow, /image-smoke\.sh pabawi:candidate \$\{\{ matrix\.profile \}\}/); + assert.match(publishWorkflow, /batteries-\$version/); + assert.match(publishWorkflow, /\$image:batteries"/); + assert.match(publishWorkflow, /DOCKERHUB_IMAGE: example42\/pabawi/); + assert.match(publishWorkflow, /secrets\.DOCKERHUB_TOKEN/); + assert.match(publishWorkflow, /docker push "\$dockerhub_tag"/); + assert.doesNotMatch(publishWorkflow, /continue-on-error/); + assert.match(publishWorkflow, /if \[\[ "\$\{\{ matrix\.profile \}\}" = batteries \]\]/); + assert.match(publishWorkflow, /trivy-batteries-ignore\.yaml/); +}); + +test("the batteries vulnerability exception is narrow and expiring", () => { + assert.match(scanScript, /--ignorefile/); + assert.match(batteriesIgnore, /id: CVE-2026-85396/); + assert.match(batteriesIgnore, /pkg:gem\/rubyzip@2\.4\.1/); + assert.match(batteriesIgnore, /rubyzip-2\.4\.1\.gemspec/); + assert.match(batteriesIgnore, /expired_at: 2026-12-31/); + assert.equal((batteriesIgnore.match(/\n\s+- id:/g) ?? []).length, 1); +}); + +test("the core smoke profile rejects integration commands", () => { + for (const command of ["ansible", "bolt", "facter", "git", "puppet", "ssh"]) { + assert.match(smokeTest, new RegExp(`\\b${command}\\b`)); + } + assert.match(smokeTest, /Core image unexpectedly contains/); +}); + +test("the batteries smoke profile requires every bundled command", () => { + const batteriesProfile = smokeTest.slice(smokeTest.indexOf(" batteries)")); + + for (const command of [ + "ansible", + "ansible-inventory", + "ansible-playbook", + "bolt", + "curl", + "facter", + "git", + "puppet", + "rsync", + "ssh", + "sshpass", + ]) { + assert.match(batteriesProfile, new RegExp(`\\b${command}\\b`)); + } +}); diff --git a/scripts/docker-build-multiarch.sh b/scripts/docker-build-multiarch.sh index f42c7494..b3005af1 100755 --- a/scripts/docker-build-multiarch.sh +++ b/scripts/docker-build-multiarch.sh @@ -6,7 +6,8 @@ set -e # Default values IMAGE_NAME="${IMAGE_NAME:-example42/pabawi}" -IMAGE_TAG="${IMAGE_TAG:-latest}" +IMAGE_TAG="${IMAGE_TAG:-}" +PROFILE="${PROFILE:-core}" PLATFORMS="${PLATFORMS:-linux/amd64,linux/arm64}" PUSH="${PUSH:-false}" LOAD="${LOAD:-false}" @@ -24,6 +25,7 @@ usage() { echo "Options:" echo " -n, --name NAME Image name (default: pabawi)" echo " -t, --tag TAG Image tag (default: latest)" + echo " --profile PROFILE Image profile: core or batteries (default: core)" echo " -p, --platforms PLATFORMS Comma-separated platforms (default: linux/amd64,linux/arm64)" echo " --push Push to registry after build" echo " --load Load image locally (single platform only)" @@ -34,6 +36,7 @@ usage() { echo " $0 --platforms linux/amd64 --load # Build for amd64 and load locally" echo " $0 --platforms linux/arm64 --load # Build for arm64 and load locally" echo " $0 --push # Build and push to registry" + echo " $0 --profile batteries --push # Build and push the full toolchain image" echo " $0 -n myrepo/pabawi -t v1.0.0 --push # Build with custom name/tag and push" exit 1 } @@ -53,6 +56,10 @@ while [[ $# -gt 0 ]]; do PLATFORMS="$2" shift 2 ;; + --profile) + PROFILE="$2" + shift 2 + ;; --push) PUSH=true shift @@ -71,6 +78,19 @@ while [[ $# -gt 0 ]]; do esac done +if [[ "$PROFILE" != "core" && "$PROFILE" != "batteries" ]]; then + echo -e "${RED}Error: --profile must be core or batteries${NC}" + exit 1 +fi + +if [[ -z "$IMAGE_TAG" ]]; then + if [[ "$PROFILE" == "batteries" ]]; then + IMAGE_TAG="batteries" + else + IMAGE_TAG="latest" + fi +fi + FULL_IMAGE_NAME="${IMAGE_NAME}:${IMAGE_TAG}" # Validate options @@ -87,6 +107,7 @@ fi echo -e "${GREEN}=== Multi-Architecture Docker Build ===${NC}" echo "Image: $FULL_IMAGE_NAME" +echo "Profile: $PROFILE" echo "Platforms: $PLATFORMS" echo "Push: $PUSH" echo "Load: $LOAD" @@ -118,6 +139,7 @@ BUILD_CMD="docker buildx build" BUILD_CMD="$BUILD_CMD --platform $PLATFORMS" BUILD_CMD="$BUILD_CMD -t $FULL_IMAGE_NAME" BUILD_CMD="$BUILD_CMD -f Dockerfile" +BUILD_CMD="$BUILD_CMD --target $PROFILE" if [[ "$PUSH" == "true" ]]; then BUILD_CMD="$BUILD_CMD --push" diff --git a/scripts/docker-run.ps1 b/scripts/docker-run.ps1 index a6c23e03..3f20168b 100755 --- a/scripts/docker-run.ps1 +++ b/scripts/docker-run.ps1 @@ -5,7 +5,7 @@ $ErrorActionPreference = "Stop" # Default values -$IMAGE_NAME = if ($env:IMAGE_NAME) { $env:IMAGE_NAME } else { "example42/pabawi:latest" } +$IMAGE_NAME = if ($env:IMAGE_NAME) { $env:IMAGE_NAME } else { "example42/pabawi:batteries" } $CONTAINER_NAME = if ($env:CONTAINER_NAME) { $env:CONTAINER_NAME } else { "pabawi" } $PORT = if ($env:PORT) { $env:PORT } else { "3000" } $DATA_PATH = if ($env:DATA_PATH) { $env:DATA_PATH } else { "./data" } diff --git a/scripts/docker-run.sh b/scripts/docker-run.sh index 3e363409..1a2460f6 100755 --- a/scripts/docker-run.sh +++ b/scripts/docker-run.sh @@ -5,7 +5,7 @@ set -e # Default values -IMAGE_NAME="${IMAGE_NAME:-example42/pabawi:latest}" +IMAGE_NAME="${IMAGE_NAME:-example42/pabawi:batteries}" CONTAINER_NAME="${CONTAINER_NAME:-pabawi}" PORT="${PORT:-3000}" DATA_PATH="${DATA_PATH:-./data}" diff --git a/scripts/documentation/contracts.test.mjs b/scripts/documentation/contracts.test.mjs index ca0731f5..9c81a4fb 100644 --- a/scripts/documentation/contracts.test.mjs +++ b/scripts/documentation/contracts.test.mjs @@ -16,6 +16,24 @@ for (const [path, item] of Object.entries(spec.paths)) { } const omissions = [...read('docs/api-contract-coverage.md').matchAll(/\| `(GET|POST|PUT|PATCH|DELETE)` \| `([^`]+)` \| ([^\n]+)/g)]; +test('release version is consistent across shipped metadata', () => { + const version = JSON.parse(read('package.json')).version; + const lock = JSON.parse(read('package-lock.json')); + assert.equal(JSON.parse(read('backend/package.json')).version, version); + assert.equal(JSON.parse(read('frontend/package.json')).version, version); + assert.equal(lock.version, version); + assert.equal(lock.packages[''].version, version); + assert.equal(lock.packages.backend.version, version); + assert.equal(lock.packages.frontend.version, version); + assert.match(read('charts/pabawi/Chart.yaml'), new RegExp(`^appVersion: "${version.replaceAll('.', '\\.')}"$`, 'm')); + assert.match(read('backend/src/server.ts'), new RegExp(`version: "${version.replaceAll('.', '\\.')}"`)); + assert.match(read('frontend/src/components/Navigation.svelte'), new RegExp(`>v${version.replaceAll('.', '\\.')}<`)); + for (const file of ['Dockerfile', 'Dockerfile.alpine', 'Dockerfile.ubuntu']) { + assert.match(read(file), new RegExp(`org\\.opencontainers\\.image\\.version="${version.replaceAll('.', '\\.')}"`)); + } + assert.match(read('CHANGELOG.md'), new RegExp(`^## \\[${version.replaceAll('.', '\\.')}\\] - \\d{4}-\\d{2}-\\d{2}$`, 'm')); +}); + test('every declared REST route is specified or explicitly omitted, with no stale entries', () => { assert.ok(actual.size > 150, 'Production route discovery unexpectedly incomplete'); const omitted = new Set(omissions.map(([, method, path]) => key(method, path))); diff --git a/scripts/setup.sh b/scripts/setup.sh index f1437394..2435c830 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -686,7 +686,7 @@ case "$INSTALL_METHOD" in -v "$PROJECT_ROOT/data:/opt/pabawi/data" \ -v "$PROJECT_ROOT/bolt-project:/opt/pabawi/bolt-project:ro" \ --restart unless-stopped \ - example42/pabawi:latest + example42/pabawi:batteries success "Pabawi container started" info "View logs: ${BOLD}docker logs -f pabawi${RESET}" info "Stop: ${BOLD}docker stop pabawi && docker rm pabawi${RESET}" @@ -694,7 +694,7 @@ case "$INSTALL_METHOD" in success "Setup complete!" echo "" info "Run manually:" - echo " ${BOLD}docker run -d --name pabawi --env-file .env -p ${PORT:-3000}:3000 -v ./data:/opt/pabawi/data example42/pabawi:latest${RESET}" + echo " ${BOLD}docker run -d --name pabawi --env-file .env -p ${PORT:-3000}:3000 -v ./data:/opt/pabawi/data example42/pabawi:batteries${RESET}" fi fi ;; diff --git a/scripts/supply-chain/image-smoke.sh b/scripts/supply-chain/image-smoke.sh index 540ce728..94574bfd 100644 --- a/scripts/supply-chain/image-smoke.sh +++ b/scripts/supply-chain/image-smoke.sh @@ -1,6 +1,43 @@ #!/usr/bin/env bash set -euo pipefail image=${1:?Usage: image-smoke.sh IMAGE} +profile=${2:?Usage: image-smoke.sh IMAGE core|batteries|bolt} + +case "$profile" in + core) + docker run --rm --entrypoint sh "$image" -c ' + for command in ansible ansible-inventory ansible-playbook bolt facter git puppet rsync ssh sshpass; do + if command -v "$command" >/dev/null 2>&1; then + echo "Core image unexpectedly contains $command" >&2 + exit 1 + fi + done + ' + ;; + batteries) + docker run --rm --entrypoint sh "$image" -c ' + for command in ansible ansible-inventory ansible-playbook bolt curl facter git puppet rsync ssh sshpass; do + command -v "$command" >/dev/null + done + ' + docker run --rm --entrypoint bolt "$image" --version + docker run --rm --entrypoint bolt "$image" task show --format json + docker run --rm --entrypoint ansible "$image" --version + docker run --rm --entrypoint ansible-inventory "$image" --version + docker run --rm --entrypoint ansible-playbook "$image" --version + docker run --rm --entrypoint puppet "$image" --version + docker run --rm --entrypoint facter "$image" --version + docker run --rm --entrypoint ssh "$image" -V + ;; + bolt) + docker run --rm --entrypoint bolt "$image" --version + docker run --rm --entrypoint bolt "$image" task show --format json + ;; + *) + echo "Unknown image profile: $profile" >&2 + exit 2 + ;; +esac docker run --rm --entrypoint node "$image" -e ' const assert = require("node:assert/strict"); @@ -15,8 +52,6 @@ db.get("SELECT 42 AS answer", (err, row) => { assert.equal(typeof require("ssh2").Client, "function"); require("pg"); ' -docker run --rm --entrypoint bolt "$image" --version -docker run --rm --entrypoint bolt "$image" task show --format json container=$(docker run -d -e JWT_SECRET="$(openssl rand -hex 32)" "$image") trap 'docker logs "$container"; docker stop "$container" >/dev/null' EXIT diff --git a/scripts/supply-chain/scan-image.sh b/scripts/supply-chain/scan-image.sh index 77e656cb..e01c19f1 100644 --- a/scripts/supply-chain/scan-image.sh +++ b/scripts/supply-chain/scan-image.sh @@ -1,11 +1,17 @@ #!/usr/bin/env bash set -euo pipefail -image=${1:?Usage: scan-image.sh IMAGE OUTPUT_DIRECTORY} +image=${1:?Usage: scan-image.sh IMAGE OUTPUT_DIRECTORY [IGNORE_FILE]} output=${2:?Output directory required} +ignore_file=${3:-} mkdir -p "$output" output=$(cd "$output" && pwd) scanner=aquasec/trivy:0.69.3@sha256:bcc376de8d77cfe086a917230e818dc9f8528e3c852f7b1aff648949b6258d1c mkdir -p "$output/cache" +gate_args=(--scanners vuln --severity HIGH,CRITICAL --ignore-unfixed) +if [[ -n "$ignore_file" ]]; then + cp "$ignore_file" "$output/scan-ignore.yaml" + gate_args+=(--ignorefile /scan/scan-ignore.yaml) +fi docker image inspect "$image" > "$output/image.json" docker save "$image" -o "$output/image.tar" # Scan the exported artifact without granting the scanner access to the Docker socket. @@ -14,4 +20,4 @@ docker run --rm -v "$output:/scan" -v "$output/cache:/root/.cache/trivy" "$scann docker run --rm -v "$output:/scan" -v "$output/cache:/root/.cache/trivy" "$scanner" --quiet image --input /scan/image.tar \ --scanners vuln --format json --output /scan/vulnerabilities.json docker run --rm -v "$output:/scan" -v "$output/cache:/root/.cache/trivy" "$scanner" --quiet image --input /scan/image.tar \ - --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 + "${gate_args[@]}" --exit-code 1 diff --git a/scripts/supply-chain/trivy-batteries-ignore.yaml b/scripts/supply-chain/trivy-batteries-ignore.yaml new file mode 100644 index 00000000..020f9546 --- /dev/null +++ b/scripts/supply-chain/trivy-batteries-ignore.yaml @@ -0,0 +1,11 @@ +vulnerabilities: + - id: CVE-2026-85396 + paths: + - opt/puppetlabs/bolt/lib/ruby/gems/3.2.0/specifications/rubyzip-2.4.1.gemspec + purls: + - pkg:gem/rubyzip@2.4.1 + expired_at: 2026-12-31 + statement: >- + OpenBolt 5.6.0 depends on winrm-fs 1.3.5, which constrains rubyzip to + the vulnerable 2.x line. Reassess when a compatible winrm-fs release is + available or before this exception expires. From 17a84a1a770725274f64cb15bf990b2944eea2ea Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Thu, 24 Sep 2026 18:56:14 +0200 Subject: [PATCH 04/21] fix(puppetdb): reset circuit breaker failures on success while closed LifetimeCount accumulated for the process lifetime while closed, so sparse failures on long-running instances tripped the breaker even when PuppetDB was healthy. Clear the streak on success, and log grouping query errors. Closes #59 Co-authored-by: Cursor --- .../integrations/puppetdb/CircuitBreaker.ts | 3 + .../integrations/puppetdb/PuppetDBService.ts | 10 ++- .../unit/integrations/CircuitBreaker.test.ts | 79 +++++++++++++++++++ 3 files changed, 88 insertions(+), 4 deletions(-) create mode 100644 backend/test/unit/integrations/CircuitBreaker.test.ts diff --git a/backend/src/integrations/puppetdb/CircuitBreaker.ts b/backend/src/integrations/puppetdb/CircuitBreaker.ts index 42fff2a7..2b976d92 100644 --- a/backend/src/integrations/puppetdb/CircuitBreaker.ts +++ b/backend/src/integrations/puppetdb/CircuitBreaker.ts @@ -165,6 +165,9 @@ export class CircuitBreaker { // Service has recovered, close the circuit this.reset(); this.transitionTo("closed"); + } else if (this.state === "closed") { + // Only consecutive failures trip the breaker; a success clears the streak + this.failureCount = 0; } } diff --git a/backend/src/integrations/puppetdb/PuppetDBService.ts b/backend/src/integrations/puppetdb/PuppetDBService.ts index 9654b7d2..587eedc7 100644 --- a/backend/src/integrations/puppetdb/PuppetDBService.ts +++ b/backend/src/integrations/puppetdb/PuppetDBService.ts @@ -656,8 +656,9 @@ export class PuppetDBService const envGroups = this.createEnvironmentGroups(envResult as PuppetDBNode[]); groups.push(...envGroups); } - } catch { - this.log("Failed to query nodes for environment grouping", "warn"); + } catch (error) { + const detail = error instanceof Error ? error.message : String(error); + this.log(`Failed to query nodes for environment grouping: ${detail}`, "warn"); } // Query 2: Group by OS family (from facts) @@ -673,8 +674,9 @@ export class PuppetDBService const osGroups = this.createOSFamilyGroups(osResult as { certname: string; "os.family": string }[]); groups.push(...osGroups); } - } catch { - this.log("Failed to query nodes for OS family grouping", "warn"); + } catch (error) { + const detail = error instanceof Error ? error.message : String(error); + this.log(`Failed to query nodes for OS family grouping: ${detail}`, "warn"); } // Cache the result diff --git a/backend/test/unit/integrations/CircuitBreaker.test.ts b/backend/test/unit/integrations/CircuitBreaker.test.ts new file mode 100644 index 00000000..d4467162 --- /dev/null +++ b/backend/test/unit/integrations/CircuitBreaker.test.ts @@ -0,0 +1,79 @@ +/** + * Unit tests for CircuitBreaker + * + * Covers consecutive-failure semantics while closed (issue #59). + */ + +import { describe, it, expect, beforeEach } from "vitest"; +import { + CircuitBreaker, + CircuitBreakerOpenError, +} from "../../../src/integrations/puppetdb/CircuitBreaker"; + +describe("CircuitBreaker", () => { + let breaker: CircuitBreaker; + + beforeEach(() => { + breaker = new CircuitBreaker({ + failureThreshold: 3, + resetTimeout: 1000, + }); + }); + + describe("failure counting while closed", () => { + it("opens after consecutive failures reach the threshold", async () => { + const fail = async (): Promise => { + throw new Error("boom"); + }; + + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + expect(breaker.getState()).toBe("closed"); + + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + expect(breaker.getState()).toBe("open"); + expect(breaker.getStats().failureCount).toBe(3); + }); + + it("resets failureCount on success while closed so sparse failures do not trip", async () => { + const fail = async (): Promise => { + throw new Error("boom"); + }; + const succeed = async (): Promise => "ok"; + + // Two failures, then a success (still under threshold) + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + expect(breaker.getStats().failureCount).toBe(2); + + await expect(breaker.execute(succeed)).resolves.toBe("ok"); + expect(breaker.getState()).toBe("closed"); + expect(breaker.getStats().failureCount).toBe(0); + + // Two more failures after the success must not open the circuit + // (would have been 4 cumulative without the reset) + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + expect(breaker.getState()).toBe("closed"); + expect(breaker.getStats().failureCount).toBe(2); + + // A third consecutive failure does open it + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + expect(breaker.getState()).toBe("open"); + }); + + it("rejects requests while open", async () => { + const fail = async (): Promise => { + throw new Error("boom"); + }; + + for (let i = 0; i < 3; i++) { + await expect(breaker.execute(fail)).rejects.toThrow("boom"); + } + + await expect(breaker.execute(async () => "ok")).rejects.toThrow( + CircuitBreakerOpenError, + ); + }); + }); +}); From 44ee0ef19a8dd493a94e734aa6591b3a70a1def2 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Wed, 21 Oct 2026 15:26:58 +0200 Subject: [PATCH 05/21] Make MCP service user provisioning repair partial state - Reuse an existing mcp-service user or MCP Service role instead of throwing when provisioning was interrupted (user created, role or assignment missing), so startup recovers on restart. - Only newly created roles get the default read permissions; existing roles keep their permissions since admins may have customized them. - Make RoleService.getRoleByName public for the role lookup. - Add unit and persisted-SQLite tests for interrupted provisioning, and document the behavior in docs/mcp.md. --- backend/src/mcp/McpServiceUser.ts | 41 +++--- backend/src/services/RoleService.ts | 2 +- backend/test/unit/mcp/McpServiceUser.test.ts | 145 ++++++++++++++++++- docs/mcp.md | 4 + 4 files changed, 162 insertions(+), 30 deletions(-) diff --git a/backend/src/mcp/McpServiceUser.ts b/backend/src/mcp/McpServiceUser.ts index 144962c1..bf4c45eb 100644 --- a/backend/src/mcp/McpServiceUser.ts +++ b/backend/src/mcp/McpServiceUser.ts @@ -16,9 +16,9 @@ export interface McpServiceUserResult { /** * Idempotent provisioning of the mcp-service user at startup. * - * If the user already exists, looks up the existing role and returns IDs. - * If not, creates the user, an "MCP Service" built-in role with all read - * permissions, and assigns the role to the user. + * Repairs missing users, roles, and assignments after incomplete provisioning. + * New roles receive all read permissions; existing roles retain their permissions + * because administrators may have customized machine access. */ export async function provisionMcpServiceUser( userService: UserService, @@ -37,11 +37,9 @@ export async function provisionMcpServiceUser( const roles = await userService.getUserRoles(existing.id); const mcpRole = roles.find((r) => r.name === MCP_ROLE_NAME); - if (!mcpRole) { - throw new Error('MCP service user exists but MCP Service role not found'); + if (mcpRole) { + return { userId: existing.id, roleId: mcpRole.id }; } - - return { userId: existing.id, roleId: mcpRole.id }; } logger.info('Provisioning MCP service user', { @@ -51,7 +49,7 @@ export async function provisionMcpServiceUser( // Create user with random password (never used for login) const password = `Mcp!${randomUUID()}`; // pragma: allowlist secret - const user = await userService.createUser({ + const user = existing ?? await userService.createUser({ username: MCP_USERNAME, email: `${MCP_USERNAME}@localhost`, password, @@ -61,21 +59,22 @@ export async function provisionMcpServiceUser( isAdmin: false, }); - // Create built-in role - const role = await roleService.createRole({ - name: MCP_ROLE_NAME, - description: 'Built-in role for MCP server with read-only access', - isBuiltIn: true, - }); + let role = await roleService.getRoleByName(MCP_ROLE_NAME); + if (!role) { + role = await roleService.createRole({ + name: MCP_ROLE_NAME, + description: 'Built-in role for MCP server with read-only access', + isBuiltIn: true, + }); - // Assign all read permissions to the role - const readPermissions = await permissionService.listPermissions({ - action: 'read', - limit: 1000, - }); + const readPermissions = await permissionService.listPermissions({ + action: 'read', + limit: 1000, + }); - for (const perm of readPermissions.items) { - await roleService.assignPermissionToRole(role.id, perm.id); + for (const perm of readPermissions.items) { + await roleService.assignPermissionToRole(role.id, perm.id); + } } // Assign role to user diff --git a/backend/src/services/RoleService.ts b/backend/src/services/RoleService.ts index 22daa661..a126e519 100644 --- a/backend/src/services/RoleService.ts +++ b/backend/src/services/RoleService.ts @@ -159,7 +159,7 @@ export class RoleService { * @param name - Role name * @returns Role or null if not found */ - private async getRoleByName(name: string): Promise { + public async getRoleByName(name: string): Promise { return this.db.queryOne( `SELECT ${ROLE_COLUMNS} FROM roles WHERE name = ?`, [name] diff --git a/backend/test/unit/mcp/McpServiceUser.test.ts b/backend/test/unit/mcp/McpServiceUser.test.ts index 96a443ca..fc30055f 100644 --- a/backend/test/unit/mcp/McpServiceUser.test.ts +++ b/backend/test/unit/mcp/McpServiceUser.test.ts @@ -1,9 +1,12 @@ -import { describe, it, expect, vi, beforeEach } from 'vitest'; +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; import { provisionMcpServiceUser } from '../../../src/mcp/McpServiceUser'; -import type { UserService } from '../../../src/services/UserService'; -import type { RoleService } from '../../../src/services/RoleService'; -import type { PermissionService } from '../../../src/services/PermissionService'; +import { UserService } from '../../../src/services/UserService'; +import { RoleService } from '../../../src/services/RoleService'; +import { PermissionService } from '../../../src/services/PermissionService'; import type { LoggerService } from '../../../src/services/LoggerService'; +import { AuthenticationService } from '../../../src/services/AuthenticationService'; +import { SQLiteAdapter } from '../../../src/database/SQLiteAdapter'; +import { initializeTestSchema } from '../../helpers/schema'; function createMockLogger(): LoggerService { return { @@ -27,6 +30,7 @@ function createMockUserService(overrides: Partial = {}): UserServic function createMockRoleService(overrides: Partial = {}): RoleService { return { createRole: vi.fn().mockResolvedValue({ id: 'role-1', name: 'MCP Service' }), + getRoleByName: vi.fn().mockResolvedValue(null), assignPermissionToRole: vi.fn().mockResolvedValue(undefined), ...overrides, } as unknown as RoleService; @@ -54,7 +58,7 @@ describe('provisionMcpServiceUser', () => { logger = createMockLogger(); }); - describe('first run — user does not exist', () => { + describe('first run: user does not exist', () => { it('should create user, role, assign permissions, and assign role', async () => { const userService = createMockUserService(); const roleService = createMockRoleService(); @@ -98,7 +102,7 @@ describe('provisionMcpServiceUser', () => { }); }); - describe('idempotency — user already exists', () => { + describe('idempotency: user already exists', () => { it('should reuse existing user and role without modification', async () => { const userService = createMockUserService({ getUserByUsername: vi.fn().mockResolvedValue({ id: 'existing-user', username: 'mcp-service' }), @@ -123,7 +127,7 @@ describe('provisionMcpServiceUser', () => { expect(userService.assignRoleToUser).not.toHaveBeenCalled(); }); - it('should throw if user exists but MCP Service role is missing', async () => { + it('should repair an existing user when MCP Service role is missing', async () => { const userService = createMockUserService({ getUserByUsername: vi.fn().mockResolvedValue({ id: 'existing-user', username: 'mcp-service' }), getUserRoles: vi.fn().mockResolvedValue([ @@ -135,7 +139,132 @@ describe('provisionMcpServiceUser', () => { await expect( provisionMcpServiceUser(userService, roleService, permissionService, logger), - ).rejects.toThrow('MCP service user exists but MCP Service role not found'); + ).resolves.toEqual({ userId: 'existing-user', roleId: 'role-1' }); + expect(userService.createUser).not.toHaveBeenCalled(); + expect(roleService.createRole).toHaveBeenCalledOnce(); + expect(roleService.assignPermissionToRole).toHaveBeenCalledTimes(2); + expect(userService.assignRoleToUser).toHaveBeenCalledWith('existing-user', 'role-1'); + }); + + it('should restore a missing assignment without changing existing role permissions', async () => { + const userService = createMockUserService({ + getUserByUsername: vi.fn().mockResolvedValue({ id: 'existing-user', username: 'mcp-service' }), + }); + const roleService = createMockRoleService({ + getRoleByName: vi.fn().mockResolvedValue({ id: 'existing-role', name: 'MCP Service' }), + }); + const permissionService = createMockPermissionService(); + + await expect( + provisionMcpServiceUser(userService, roleService, permissionService, logger), + ).resolves.toEqual({ userId: 'existing-user', roleId: 'existing-role' }); + expect(userService.createUser).not.toHaveBeenCalled(); + expect(roleService.createRole).not.toHaveBeenCalled(); + expect(permissionService.listPermissions).not.toHaveBeenCalled(); + expect(roleService.assignPermissionToRole).not.toHaveBeenCalled(); + expect(userService.assignRoleToUser).toHaveBeenCalledWith('existing-user', 'existing-role'); + }); + + it('should reuse an existing role when creating a missing user', async () => { + const userService = createMockUserService(); + const roleService = createMockRoleService({ + getRoleByName: vi.fn().mockResolvedValue({ id: 'existing-role', name: 'MCP Service' }), + }); + const permissionService = createMockPermissionService(); + + await expect( + provisionMcpServiceUser(userService, roleService, permissionService, logger), + ).resolves.toEqual({ userId: 'user-1', roleId: 'existing-role' }); + expect(userService.createUser).toHaveBeenCalledOnce(); + expect(roleService.createRole).not.toHaveBeenCalled(); + expect(permissionService.listPermissions).not.toHaveBeenCalled(); + expect(userService.assignRoleToUser).toHaveBeenCalledWith('user-1', 'existing-role'); }); }); }); + +describe('provisionMcpServiceUser with persisted RBAC state', () => { + let db: SQLiteAdapter; + let userService: UserService; + let roleService: RoleService; + let permissionService: PermissionService; + let logger: LoggerService; + + beforeEach(async () => { + db = new SQLiteAdapter(':memory:'); + await db.initialize(); + await initializeTestSchema(db); + const authService = new AuthenticationService(db, 'test-mcp-secret'); // pragma: allowlist secret + userService = new UserService(db, authService); + roleService = new RoleService(db); + permissionService = new PermissionService(db); + logger = createMockLogger(); + }); + + afterEach(async () => { + vi.restoreAllMocks(); + await db.close(); + }); + + it('should recover on restart after role creation fails with the user already persisted', async () => { + vi.spyOn(roleService, 'createRole').mockRejectedValueOnce(new Error('Interrupted role creation')); + + await expect( + provisionMcpServiceUser(userService, roleService, permissionService, logger), + ).rejects.toThrow('Interrupted role creation'); + const user = await userService.getUserByUsername('mcp-service'); + expect(user).not.toBeNull(); + + const result = await provisionMcpServiceUser(userService, roleService, permissionService, logger); + + expect(result.userId).toBe(user?.id); + expect(await userService.getUserRoles(result.userId)).toEqual( + expect.arrayContaining([expect.objectContaining({ id: result.roleId, name: 'MCP Service' })]), + ); + const permissions = await roleService.getRolePermissions(result.roleId); + const readPermissions = await permissionService.listPermissions({ action: 'read', limit: 1000 }); + expect(permissions.map((permission) => permission.id).sort()).toEqual( + readPermissions.items.map((permission) => permission.id).sort(), + ); + await expect( + provisionMcpServiceUser(userService, roleService, permissionService, logger), + ).resolves.toEqual(result); + }); + + it('should recover on restart after role assignment fails', async () => { + vi.spyOn(userService, 'assignRoleToUser').mockRejectedValueOnce(new Error('Interrupted role assignment')); + + await expect( + provisionMcpServiceUser(userService, roleService, permissionService, logger), + ).rejects.toThrow('Interrupted role assignment'); + const role = await roleService.getRoleByName('MCP Service'); + expect(role).not.toBeNull(); + + const result = await provisionMcpServiceUser(userService, roleService, permissionService, logger); + + expect(result.roleId).toBe(role?.id); + expect(await userService.getUserRoles(result.userId)).toEqual( + expect.arrayContaining([expect.objectContaining({ id: result.roleId })]), + ); + await expect( + provisionMcpServiceUser(userService, roleService, permissionService, logger), + ).resolves.toEqual(result); + }); + + it('should preserve customized permissions when reusing an unassigned role', async () => { + const role = await roleService.createRole({ + name: 'MCP Service', description: 'Restricted machine access', isBuiltIn: true, + }); + const readPermissions = await permissionService.listPermissions({ action: 'read', limit: 1000 }); + await roleService.assignPermissionToRole(role.id, readPermissions.items[0].id); + const permissions = await roleService.getRolePermissions(role.id); + + const result = await provisionMcpServiceUser(userService, roleService, permissionService, logger); + + expect(result.roleId).toBe(role.id); + expect(await roleService.getRolePermissions(role.id)).toEqual(permissions); + expect(await userService.getUserRoles(result.userId)).toEqual( + expect.arrayContaining([expect.objectContaining({ id: role.id })]), + ); + }); +}); diff --git a/docs/mcp.md b/docs/mcp.md index d8be8520..02fd5b92 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -29,6 +29,10 @@ When enabled, Pabawi: 3. Assigns the role to the service user 4. Starts the MCP server and registers the `/mcp` endpoint +Startup reuses existing service users and roles, and repairs a missing role or +role assignment after incomplete provisioning. Only newly created roles receive +the default read permissions; existing role permissions retain any customizations. + All MCP endpoints require bearer authentication, using an access JWT or the configured static token. The MCP server calls services directly within the backend process. Every tool uses the authenticated caller's current permissions. JWT callers use their own account; only the configured static credential uses `mcp-service`. ## Authentication From 2c23a95b81a2492d6dec5f3a76ea0b3afe06e76f Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Wed, 21 Oct 2026 18:27:41 +0200 Subject: [PATCH 06/21] Add reset-password CLI for local account recovery - Locked-out admins had no way back in without editing the database by hand. The CLI resets a local user's password from the shell on the host that owns the database. - The password is read from a hidden prompt, stdin or --generate, and is never accepted as an argument, so it stays out of shell history. - It applies the normal password policy, clears lockouts and failed-login counters, revokes all existing sessions, and writes a cli_password_reset audit entry that omits the password. - Disabled accounts are only reactivated when --activate is given. - Document the command in the README, troubleshooting guide and changelog, and add an npm script plus unit tests. --- CHANGELOG.md | 11 +- README.md | 1 + backend/package.json | 1 + backend/src/cli/reset-password.ts | 163 ++++++++++++++++++ backend/src/cli/resetUserPassword.ts | 104 +++++++++++ .../test/unit/cli/resetUserPassword.test.ts | 142 +++++++++++++++ docs/troubleshooting.md | 22 +++ 7 files changed, 443 insertions(+), 1 deletion(-) create mode 100644 backend/src/cli/reset-password.ts create mode 100644 backend/src/cli/resetUserPassword.ts create mode 100644 backend/test/unit/cli/resetUserPassword.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e84a2e8..f7112b74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,15 @@ # Changelog -## [1.5.1] - 2026-09-16 +## [1.6.0] - Unreleased + +### Added + +- `reset-password` CLI for account recovery: `npm run reset-password --workspace=backend -- --username admin` + (or `node dist/cli/reset-password.js` in built installs and containers). It + reads the password from a hidden prompt, stdin or `--generate`, applies the + password policy, clears lockouts, revokes all existing sessions and writes a + `cli_password_reset` audit entry. See + [troubleshooting](docs/troubleshooting.md#reset-a-local-users-password-account-recovery). ### Container images diff --git a/README.md b/README.md index eef9c6e7..50d41f7c 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,7 @@ Full reference: [Configuration Guide](docs/configuration.md). Architecture and c ## The usuals - **Documentation:** [User Guide](docs/user-guide.md) · [Architecture](docs/architecture.md) · [API Reference](docs/api.md) · [Permissions & RBAC](docs/permissions-rbac.md) · [MCP Server](docs/mcp.md) +- **Locked out?** Reset a local password from the shell: `npm run reset-password --workspace=backend -- --username admin` ([details](docs/troubleshooting.md#reset-a-local-users-password-account-recovery)) - **Troubleshooting:** [Troubleshooting Guide](docs/troubleshooting.md) — for help beyond that, enable expert mode for diagnostics and [open a GitHub issue](https://github.com/example42/pabawi/issues) with version info, sanitized config, and reproduction steps - **Development & contributing:** [Development Guide](docs/development.md) - **Version history:** [CHANGELOG](CHANGELOG.md) diff --git a/backend/package.json b/backend/package.json index 3d08be63..39e8a076 100644 --- a/backend/package.json +++ b/backend/package.json @@ -7,6 +7,7 @@ "dev": "tsx watch src/server.ts", "build": "node ../scripts/compilation/backend.mjs", "start": "node dist/server.js", + "reset-password": "tsx src/cli/reset-password.ts", "test": "vitest --run --passWithNoTests", "test:watch": "vitest", "lint": "eslint src --ext .ts --max-warnings 0", diff --git a/backend/src/cli/reset-password.ts b/backend/src/cli/reset-password.ts new file mode 100644 index 00000000..248bfe58 --- /dev/null +++ b/backend/src/cli/reset-password.ts @@ -0,0 +1,163 @@ +/** + * Reset a local user's password from the command line (account recovery). + * + * Usage (from the backend directory, with the same environment as the server): + * npm run reset-password -- [--username admin] [--generate | --password-stdin] [--activate] + * node dist/cli/reset-password.js ... (built / Docker image) + * + * The password is never accepted as an argument: it is read from a hidden + * prompt, from stdin (--password-stdin), or generated (--generate). + * Run it on the host that owns the database; shell access is the trust boundary. + */ +import { userInfo } from 'os'; +import { ConfigService } from '../config/ConfigService'; +import { DatabaseService } from '../database/DatabaseService'; +import { AuditLoggingService } from '../services/AuditLoggingService'; +import { AuthenticationService } from '../services/AuthenticationService'; +import { UserService } from '../services/UserService'; +import { generatePassword, resetUserPassword } from './resetUserPassword'; + +interface CliArgs { + username: string; + generate: boolean; + passwordStdin: boolean; + activate: boolean; + help: boolean; +} + +const USAGE = `Usage: reset-password [options] + + --username Account to reset (default: admin) + --generate Generate a random password and print it once + --password-stdin Read the new password from stdin (one line) + --activate Also reactivate the account if it is disabled + -h, --help Show this help + +Without --generate or --password-stdin the password is prompted for twice.`; + +export function parseArgs(argv: string[]): CliArgs { + const args: CliArgs = { + username: 'admin', generate: false, passwordStdin: false, activate: false, help: false, + }; + for (let i = 0; i < argv.length; i++) { + const arg = argv[i]; + switch (arg) { + case '--username': { + const value = argv[++i]; + if (!value || value.startsWith('--')) throw new Error('--username requires a value'); + args.username = value; + break; + } + case '--generate': args.generate = true; break; + case '--password-stdin': args.passwordStdin = true; break; + case '--activate': args.activate = true; break; + case '-h': + case '--help': args.help = true; break; + default: throw new Error(`Unknown argument: ${arg}`); + } + } + if (args.generate && args.passwordStdin) { + throw new Error('--generate and --password-stdin are mutually exclusive'); + } + return args; +} + +async function readStdinLine(): Promise { + const chunks: Buffer[] = []; + for await (const chunk of process.stdin) chunks.push(chunk as Buffer); + return Buffer.concat(chunks).toString('utf8').split(/\r?\n/)[0]; +} + +/** Prompt without echoing input. Requires an interactive TTY. */ +function promptHidden(label: string): Promise { + return new Promise((resolve, reject) => { + const stdin = process.stdin; + if (!stdin.isTTY) { + reject(new Error('No TTY available: use --password-stdin or --generate')); + return; + } + process.stderr.write(label); + let value = ''; + stdin.setRawMode(true); + stdin.resume(); + stdin.setEncoding('utf8'); + const onData = (key: string): void => { + for (const ch of key) { + if (ch === '\u0003') { // Ctrl-C + cleanup(); + reject(new Error('Aborted')); + return; + } + if (ch === '\r' || ch === '\n' || ch === '\u0004') { + cleanup(); + process.stderr.write('\n'); + resolve(value); + return; + } + if (ch === '\u007f' || ch === '\b') value = value.slice(0, -1); + else value += ch; + } + }; + const cleanup = (): void => { + stdin.setRawMode(false); + stdin.pause(); + stdin.removeListener('data', onData); + }; + stdin.on('data', onData); + }); +} + +async function obtainPassword(args: CliArgs): Promise<{ password: string; generated: boolean }> { + if (args.generate) return { password: generatePassword(), generated: true }; + if (args.passwordStdin) return { password: await readStdinLine(), generated: false }; + const first = await promptHidden('New password: '); + const second = await promptHidden('Repeat password: '); + if (first !== second) throw new Error('Passwords do not match'); + return { password: first, generated: false }; +} + +async function main(): Promise { + const args = parseArgs(process.argv.slice(2)); + if (args.help) { + process.stdout.write(`${USAGE}\n`); + return; + } + + const { password, generated } = await obtainPassword(args); + + const configService = new ConfigService(); + const config = configService.getConfig(); + + const databaseService = new DatabaseService(config.databasePath, config.dbType, config.databaseUrl); + await databaseService.initialize(); + try { + const db = databaseService.getAdapter(); + const auditLogger = new AuditLoggingService(db); + const authService = new AuthenticationService(db, configService.getJwtSecret(), auditLogger); + const userService = new UserService(db, authService); + + const result = await resetUserPassword( + { db, userService, authService, auditLogger }, + { username: args.username, password, activate: args.activate, invokedBy: userInfo().username }, + ); + + process.stdout.write(`Password reset for "${result.username}". All existing sessions were revoked.\n`); + if (result.reactivated) process.stdout.write('Account was reactivated.\n'); + if (result.federationOnly) { + process.stdout.write('Note: this account had no local password (SSO only); local login is now enabled.\n'); + } + if (generated) process.stdout.write(`Generated password (shown once): ${password}\n`); + } finally { + await databaseService.close(); + } +} + +if (require.main === module) { + main().then( + () => process.exit(0), + (error: unknown) => { + process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`); + process.exit(1); + }, + ); +} diff --git a/backend/src/cli/resetUserPassword.ts b/backend/src/cli/resetUserPassword.ts new file mode 100644 index 00000000..45f32047 --- /dev/null +++ b/backend/src/cli/resetUserPassword.ts @@ -0,0 +1,104 @@ +import { randomInt } from 'crypto'; +import type { DatabaseAdapter } from '../database/DatabaseAdapter'; +import type { AuthenticationService } from '../services/AuthenticationService'; +import type { AuditLoggingService } from '../services/AuditLoggingService'; +import type { UserService } from '../services/UserService'; +import { validatePassword } from '../utils/passwordValidation'; + +export interface ResetPasswordDeps { + db: DatabaseAdapter; + userService: UserService; + authService: AuthenticationService; + auditLogger: AuditLoggingService; +} + +export interface ResetPasswordOptions { + username: string; + password: string; + /** Reactivate the account if it is disabled. Off by default. */ + activate?: boolean; + /** OS account that ran the CLI, recorded in the audit log. */ + invokedBy?: string; +} + +export interface ResetPasswordResult { + userId: string; + username: string; + reactivated: boolean; + federationOnly: boolean; +} + +const GENERATED_LENGTH = 20; +const UPPER = 'ABCDEFGHJKLMNPQRSTUVWXYZ'; +const LOWER = 'abcdefghijkmnopqrstuvwxyz'; +const DIGITS = '23456789'; +const SPECIAL = '!@#$%^&*()-_=+'; + +/** + * Generate a random password that satisfies validatePassword(). + * Uses crypto.randomInt, so the output is uniformly random per character. + */ +export function generatePassword(): string { + const all = UPPER + LOWER + DIGITS + SPECIAL; + const pick = (set: string): string => set[randomInt(set.length)]; + const chars = [pick(UPPER), pick(LOWER), pick(DIGITS), pick(SPECIAL)]; + while (chars.length < GENERATED_LENGTH) chars.push(pick(all)); + // Fisher-Yates shuffle so the guaranteed characters are not positional + for (let i = chars.length - 1; i > 0; i--) { + const j = randomInt(i + 1); + [chars[i], chars[j]] = [chars[j], chars[i]]; + } + return chars.join(''); +} + +/** + * Reset a local user's password out of band (CLI recovery path). + * + * Validates the password before touching anything, then: sets the new hash, + * clears lockouts and failed-login counters, rotates the session version so + * every issued access/refresh token stops working, and writes an audit entry. + * The password itself is never logged or audited. + * + * @throws Error if the user does not exist or the password is not acceptable + */ +export async function resetUserPassword( + deps: ResetPasswordDeps, + options: ResetPasswordOptions, +): Promise { + const { db, userService, authService, auditLogger } = deps; + + const user = await userService.getUserByUsername(options.username); + if (!user) { + throw new Error(`User not found: ${options.username}`); + } + + const validation = validatePassword(options.password); + if (!validation.valid) { + throw new Error(`Password validation failed: ${validation.errors.join(', ')}`); + } + + const reactivate = options.activate === true && user.isActive !== 1; + const federationOnly = !user.passwordHash; + + await userService.updateUser(user.id, { + password: options.password, + ...(reactivate ? { isActive: true } : {}), + }); + + // Unlock first, then clear the cumulative counters the unlock does not touch + await authService.unlockAccount(user.username); + await db.execute('DELETE FROM login_attempt_counters WHERE username = ?', [user.username]); + + // updateUser does not rotate the session version; do it explicitly + await authService.revokeAllUserTokens(user.id); + + await auditLogger.logAdminAction('cli_password_reset', user.id, { + source: 'cli', + username: user.username, + invokedBy: options.invokedBy ?? 'unknown', + reactivated: reactivate, + federationOnly, + }); + + return { userId: user.id, username: user.username, reactivated: reactivate, federationOnly }; +} diff --git a/backend/test/unit/cli/resetUserPassword.test.ts b/backend/test/unit/cli/resetUserPassword.test.ts new file mode 100644 index 00000000..bdafc6d7 --- /dev/null +++ b/backend/test/unit/cli/resetUserPassword.test.ts @@ -0,0 +1,142 @@ +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { SQLiteAdapter } from '../../../src/database/SQLiteAdapter'; +import { AuthenticationService } from '../../../src/services/AuthenticationService'; +import { AuditLoggingService } from '../../../src/services/AuditLoggingService'; +import { UserService } from '../../../src/services/UserService'; +import { validatePassword } from '../../../src/utils/passwordValidation'; +import { generatePassword, resetUserPassword } from '../../../src/cli/resetUserPassword'; +import { parseArgs } from '../../../src/cli/reset-password'; +import { initializeTestSchema } from '../../helpers/schema'; + +const OLD_PASSWORD = 'OldPass123!'; // pragma: allowlist secret +const NEW_PASSWORD = 'NewPass456@'; // pragma: allowlist secret + +describe('resetUserPassword', () => { + let db: SQLiteAdapter; + let authService: AuthenticationService; + let userService: UserService; + let auditLogger: AuditLoggingService; + let userId: string; + + const deps = () => ({ db, userService, authService, auditLogger }); + + beforeEach(async () => { + db = new SQLiteAdapter(':memory:'); + await db.initialize(); + await initializeTestSchema(db); + auditLogger = new AuditLoggingService(db); + authService = new AuthenticationService(db, 'test-secret-test-secret-test-secret', auditLogger); + userService = new UserService(db, authService); + const user = await userService.createUser({ + username: 'admin', + email: 'admin@example.com', + password: OLD_PASSWORD, + firstName: 'Ad', + lastName: 'Min', + isActive: true, + isAdmin: true, + }); + userId = user.id; + }); + + afterEach(async () => { + await db.close(); + }); + + it('sets the new password, which verifies, and invalidates the old one', async () => { + await resetUserPassword(deps(), { username: 'admin', password: NEW_PASSWORD }); + const user = await userService.getUserById(userId); + expect(await authService.verifyPassword(NEW_PASSWORD, user!.passwordHash)).toBe(true); + expect(await authService.verifyPassword(OLD_PASSWORD, user!.passwordHash)).toBe(false); + }); + + it('rotates the session version so issued tokens are revoked', async () => { + const before = await db.queryOne<{ v: string }>('SELECT session_version AS v FROM users WHERE id = ?', [userId]); + await resetUserPassword(deps(), { username: 'admin', password: NEW_PASSWORD }); + const after = await db.queryOne<{ v: string }>('SELECT session_version AS v FROM users WHERE id = ?', [userId]); + expect(after!.v).not.toBe(before!.v); + }); + + it('clears lockouts and failed-login counters', async () => { + const now = new Date().toISOString(); + await db.execute( + `INSERT INTO account_lockouts (username, lockout_type, locked_at, locked_until, failed_attempts, last_attempt_at) + VALUES (?, 'permanent', ?, NULL, 5, ?)`, + ['admin', now, now], + ); + await db.execute( + 'INSERT INTO login_attempt_counters (username, cumulative_failed_attempts, last_failed_at) VALUES (?, 7, ?)', + ['admin', now], + ); + await resetUserPassword(deps(), { username: 'admin', password: NEW_PASSWORD }); + expect(await db.query('SELECT 1 FROM account_lockouts WHERE username = ?', ['admin'])).toHaveLength(0); + expect(await db.query('SELECT 1 FROM login_attempt_counters WHERE username = ?', ['admin'])).toHaveLength(0); + }); + + it('writes an audit entry that does not contain the password', async () => { + await resetUserPassword(deps(), { username: 'admin', password: NEW_PASSWORD, invokedBy: 'root' }); + const rows = await db.query<{ action: string; details: string }>( + 'SELECT "action", details FROM audit_logs WHERE "action" = ?', + ['cli_password_reset'], + ); + expect(rows).toHaveLength(1); + expect(rows[0].details).toContain('root'); + expect(rows[0].details).not.toContain(NEW_PASSWORD); + }); + + it('rejects a weak password and leaves the account untouched', async () => { + const before = await userService.getUserById(userId); + await expect(resetUserPassword(deps(), { username: 'admin', password: 'weak' })) + .rejects.toThrow('Password validation failed'); + const after = await userService.getUserById(userId); + expect(after!.passwordHash).toBe(before!.passwordHash); + }); + + it('fails for an unknown user', async () => { + await expect(resetUserPassword(deps(), { username: 'nobody', password: NEW_PASSWORD })) + .rejects.toThrow('User not found: nobody'); + }); + + it('does not reactivate a disabled account unless asked', async () => { + await db.execute('UPDATE users SET is_active = 0 WHERE id = ?', [userId]); + const plain = await resetUserPassword(deps(), { username: 'admin', password: NEW_PASSWORD }); + expect(plain.reactivated).toBe(false); + expect((await userService.getUserById(userId))!.isActive).toBe(0); + + const activated = await resetUserPassword(deps(), { username: 'admin', password: NEW_PASSWORD, activate: true }); + expect(activated.reactivated).toBe(true); + expect((await userService.getUserById(userId))!.isActive).toBe(1); + }); +}); + +describe('generatePassword', () => { + it('always satisfies the password policy and is not constant', () => { + const seen = new Set(); + for (let i = 0; i < 200; i++) { + const p = generatePassword(); + expect(validatePassword(p).valid).toBe(true); + seen.add(p); + } + expect(seen.size).toBe(200); + }); +}); + +describe('parseArgs', () => { + it('defaults to admin with prompt mode', () => { + expect(parseArgs([])).toMatchObject({ username: 'admin', generate: false, passwordStdin: false, activate: false }); + }); + + it('parses flags', () => { + expect(parseArgs(['--username', 'bob', '--generate', '--activate'])) + .toMatchObject({ username: 'bob', generate: true, activate: true }); + }); + + it('rejects unknown args, including a password on the command line', () => { + expect(() => parseArgs(['--password', 'x'])).toThrow('Unknown argument'); + }); + + it('rejects conflicting modes and missing values', () => { + expect(() => parseArgs(['--generate', '--password-stdin'])).toThrow('mutually exclusive'); + expect(() => parseArgs(['--username'])).toThrow('requires a value'); + }); +}); diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index df6a7c15..a906da77 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -245,6 +245,28 @@ color: false | "JWT malformed" | Token expired or tampered. Log out and log in again | | No login prompt | Check whether a valid session is already stored. REST authentication is mandatory; test an API call without Authorization to verify rejection. | +### Reset a local user's password (account recovery) + +Run on the host that owns the database, with the same environment as the server (`backend/.env`, `JWT_SECRET`, `DATABASE_PATH` or `DATABASE_URL`): + +```bash +# from a source checkout +npm run reset-password --workspace=backend -- --username admin + +# built install or Docker image +node dist/cli/reset-password.js --username admin +docker exec -it pabawi node dist/cli/reset-password.js --username admin +``` + +| Flag | Effect | +|---|---| +| `--username ` | Account to reset (default `admin`) | +| `--generate` | Generate a random password and print it once | +| `--password-stdin` | Read the password from stdin instead of the hidden prompt | +| `--activate` | Also reactivate a disabled account (off by default) | + +The password is never accepted as an argument. The command applies the normal password policy, clears lockouts and failed-login counters, revokes every issued token and refresh token for the account, and writes a `cli_password_reset` audit entry (no password included). Access to the shell and database is the trust boundary. + --- ## FAQ From a739cf296fb01b872ed4b234eba971e51f0bb783 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Wed, 21 Oct 2026 18:58:01 +0200 Subject: [PATCH 07/21] Add external identity boundaries for LDAP-ready auth (migration 031) - Add migration 031 for SQLite and PostgreSQL: identities are now unique on (provider, issuer, subject), and users get a local_auth_enabled scope, nullable non-unique external email, and a display_name field. - Make federated role grants identity-owned with source keys, so Entra sync only removes its own grants. Preserve legacy grants and detached ones as manual assignments. - Add LDAP directory state, group mapping, validation and lease tables, with triggers that withdraw grants and invalidate authorization state when mappings change. - Replace ambiguous findByEmail with findLocalByEmail and findAllByEmail. Entra provisioning still rejects any email collision without linking. - Reserve the "ldap:" username prefix and reject local passwords for LDAP identities. - Render null email and displayName safely in the frontend and update the API and OpenAPI docs. - Add upgrade, rollback and concurrency tests on both adapters, and the LDAP implementation plan (package 1 of 7). --- ..._external_identity_boundaries.postgres.sql | 170 +++++ ...31_external_identity_boundaries.sqlite.sql | 232 +++++++ backend/src/services/AuthenticationService.ts | 19 +- backend/src/services/EntraIdService.ts | 23 +- backend/src/services/GroupService.ts | 2 +- backend/src/services/UserService.ts | 63 +- backend/test/UserService.password.test.ts | 114 +--- .../database/BatchLifecycleMigration.test.ts | 2 +- .../external-identity-boundaries.test.ts | 348 ++++++++++ .../database/migration-integration.test.ts | 10 +- backend/test/database/rbac-schema.test.ts | 5 +- backend/test/database/sso-concurrency.test.ts | 6 +- .../EntraIdAuthCode.property.test.ts | 2 +- .../EntraIdCallback.property.test.ts | 14 +- .../EntraIdGroupSync.property.test.ts | 28 +- .../EntraIdProvisioning.property.test.ts | 14 +- .../user/email-uniqueness.property.test.ts | 2 +- .../AuthenticationService.bruteforce.test.ts | 113 +--- .../test/unit/services/EntraIdService.test.ts | 24 +- docs/api.md | 8 + docs/internal/plans/ldap-authentication.md | 602 ++++++++++++++++++ docs/openapi.yaml | 9 + .../src/components/GroupDetailDialog.svelte | 4 +- .../src/components/UserDetailDialog.svelte | 4 +- .../user-contact-nullability.test.ts | 45 ++ frontend/src/lib/auth.svelte.ts | 3 +- frontend/src/lib/auth.test.ts | 1 + frontend/src/lib/permission-state.test.ts | 2 +- frontend/src/pages/UserManagementPage.svelte | 6 +- 29 files changed, 1566 insertions(+), 309 deletions(-) create mode 100644 backend/src/database/migrations/031_external_identity_boundaries.postgres.sql create mode 100644 backend/src/database/migrations/031_external_identity_boundaries.sqlite.sql create mode 100644 backend/test/database/external-identity-boundaries.test.ts create mode 100644 docs/internal/plans/ldap-authentication.md create mode 100644 frontend/src/components/user-contact-nullability.test.ts diff --git a/backend/src/database/migrations/031_external_identity_boundaries.postgres.sql b/backend/src/database/migrations/031_external_identity_boundaries.postgres.sql new file mode 100644 index 00000000..8b179ac8 --- /dev/null +++ b/backend/src/database/migrations/031_external_identity_boundaries.postgres.sql @@ -0,0 +1,170 @@ +ALTER TABLE users DROP CONSTRAINT users_email_key; +ALTER TABLE users ALTER COLUMN email DROP NOT NULL; +ALTER TABLE users ADD COLUMN local_auth_enabled INTEGER NOT NULL DEFAULT 1 CHECK (local_auth_enabled IN (0, 1)); +ALTER TABLE users ADD COLUMN display_name TEXT; +UPDATE users SET local_auth_enabled = 0 WHERE password_hash IS NULL; +ALTER TABLE users ADD CONSTRAINT users_local_email_required CHECK (local_auth_enabled = 0 OR (email IS NOT NULL AND length(trim(email)) > 0)); +ALTER TABLE users ADD CONSTRAINT users_local_password_scope CHECK (local_auth_enabled = 1 OR password_hash IS NULL); +ALTER TABLE federated_identities DROP CONSTRAINT federated_identities_provider_subject_key; +ALTER TABLE federated_identities ADD CONSTRAINT federated_identity_scope UNIQUE(provider, issuer, subject); +ALTER TABLE federated_identities ADD CONSTRAINT federated_identity_owner UNIQUE(id, user_id); +ALTER TABLE federated_identities ADD CONSTRAINT federated_identity_directory UNIQUE(id, provider, issuer); +DROP INDEX idx_federated_identities_lookup; +CREATE INDEX idx_federated_identities_lookup ON federated_identities(provider, issuer, subject); +DROP VIEW effective_user_roles; + +CREATE UNIQUE INDEX idx_users_local_email ON users(email) WHERE local_auth_enabled = 1; + +CREATE TABLE ldap_directory_state ( + directory_id TEXT PRIMARY KEY, + mapping_revision BIGINT NOT NULL DEFAULT 0 CHECK (mapping_revision >= 0), + config_revision TEXT NOT NULL DEFAULT '' +); + +CREATE TABLE ldap_identity_metadata ( + identity_id TEXT PRIMARY KEY, + provider TEXT NOT NULL DEFAULT 'ldap' CHECK (provider = 'ldap'), + directory_id TEXT NOT NULL REFERENCES ldap_directory_state(directory_id), + login_name TEXT NOT NULL, + dn TEXT NOT NULL, + FOREIGN KEY (identity_id, provider, directory_id) + REFERENCES federated_identities(id, provider, issuer) ON DELETE CASCADE +); + +CREATE INDEX idx_ldap_identity_directory ON ldap_identity_metadata(directory_id); + +CREATE UNIQUE INDEX idx_ldap_identity_scope ON ldap_identity_metadata(identity_id, directory_id); + +CREATE TABLE external_group_mappings ( + id TEXT PRIMARY KEY, + directory_id TEXT NOT NULL REFERENCES ldap_directory_state(directory_id), + group_subject TEXT NOT NULL, + group_dn TEXT NOT NULL, + group_name TEXT NOT NULL, + role_id TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE, + enabled INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0, 1)), + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + UNIQUE(directory_id, group_subject, role_id), + UNIQUE(id, role_id, directory_id) +); + +CREATE TABLE federated_user_roles_new ( + user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE, + role_id TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE, + identity_id TEXT NOT NULL, + source_key TEXT NOT NULL CHECK (length(source_key) > 0), + mapping_id TEXT, + directory_id TEXT, + PRIMARY KEY (identity_id, role_id, source_key), + FOREIGN KEY (identity_id, user_id) REFERENCES federated_identities(id, user_id) ON DELETE CASCADE, + FOREIGN KEY (identity_id, directory_id) REFERENCES ldap_identity_metadata(identity_id, directory_id) ON DELETE CASCADE, + FOREIGN KEY (mapping_id, role_id, directory_id) REFERENCES external_group_mappings(id, role_id, directory_id) ON DELETE CASCADE, + CHECK ((mapping_id IS NULL AND directory_id IS NULL) OR (mapping_id IS NOT NULL AND directory_id IS NOT NULL)) +); + +-- Detached historical grants have no provable identity owner. Preserve access. +INSERT INTO user_roles (user_id, role_id, assigned_at) +SELECT f.user_id, f.role_id, CAST(CURRENT_TIMESTAMP AS TEXT) FROM federated_user_roles f +WHERE NOT EXISTS (SELECT 1 FROM federated_identities i WHERE i.user_id = f.user_id AND i.provider = 'entra-id') +ON CONFLICT(user_id, role_id) DO NOTHING; + +INSERT INTO federated_user_roles_new (user_id, role_id, identity_id, source_key) +SELECT f.user_id, f.role_id, i.id, 'legacy' +FROM federated_user_roles f JOIN federated_identities i ON i.user_id = f.user_id AND i.provider = 'entra-id'; + +DROP TABLE federated_user_roles; + +ALTER TABLE federated_user_roles_new RENAME TO federated_user_roles; + +CREATE INDEX idx_federated_roles_user ON federated_user_roles(user_id, role_id); + +CREATE INDEX idx_federated_roles_mapping ON federated_user_roles(mapping_id); + +CREATE UNIQUE INDEX idx_federated_roles_mapping_identity ON federated_user_roles(identity_id, mapping_id) WHERE mapping_id IS NOT NULL; + +CREATE VIEW effective_user_roles AS +SELECT user_id, role_id FROM user_roles +UNION SELECT user_id, role_id FROM federated_user_roles; + +CREATE TABLE ldap_validation_state ( + identity_id TEXT PRIMARY KEY REFERENCES ldap_identity_metadata(identity_id) ON DELETE CASCADE, + last_validated_at BIGINT, + validation_generation BIGINT NOT NULL DEFAULT 0 CHECK (validation_generation >= 0), + mapping_revision BIGINT NOT NULL DEFAULT 0 CHECK (mapping_revision >= 0), + config_revision TEXT NOT NULL, + CHECK (last_validated_at IS NULL OR last_validated_at >= 0) +); + +CREATE TABLE ldap_validation_leases ( + identity_id TEXT PRIMARY KEY REFERENCES ldap_identity_metadata(identity_id) ON DELETE CASCADE, + lease_owner TEXT, + lease_expires_at BIGINT, + fencing_generation BIGINT NOT NULL DEFAULT 0 CHECK (fencing_generation >= 0), + CHECK ((lease_owner IS NULL AND lease_expires_at IS NULL) OR (lease_owner IS NOT NULL AND lease_expires_at IS NOT NULL)) +); + +CREATE INDEX idx_ldap_lease_expiry ON ldap_validation_leases(lease_expires_at); + +CREATE TRIGGER authz_federated_roles AFTER INSERT OR UPDATE OR DELETE ON federated_user_roles +FOR EACH STATEMENT EXECUTE FUNCTION pabawi_authorization_changed(); +CREATE FUNCTION pabawi_revoke_local_scope_sessions() RETURNS trigger LANGUAGE plpgsql AS $$ +BEGIN + IF NEW.local_auth_enabled IS DISTINCT FROM OLD.local_auth_enabled THEN + NEW.session_version := replace(gen_random_uuid()::text, '-', ''); + END IF; + RETURN NEW; +END; +$$; +CREATE TRIGGER revoke_local_scope_sessions BEFORE UPDATE OF local_auth_enabled ON users +FOR EACH ROW EXECUTE FUNCTION pabawi_revoke_local_scope_sessions(); + + +CREATE FUNCTION pabawi_ldap_mapping_insert() RETURNS trigger LANGUAGE plpgsql AS $$ +BEGIN + UPDATE ldap_directory_state SET mapping_revision = mapping_revision + 1 + WHERE directory_id IN (SELECT NEW.directory_id); + UPDATE ldap_validation_state SET last_validated_at = NULL + WHERE identity_id IN (SELECT identity_id FROM ldap_identity_metadata WHERE directory_id IN (SELECT NEW.directory_id)); + UPDATE authorization_state SET revision = replace(gen_random_uuid()::text, '-', '') WHERE id = 1; + RETURN NULL; +END; +$$; +CREATE TRIGGER ldap_mapping_insert AFTER INSERT ON external_group_mappings +FOR EACH ROW EXECUTE FUNCTION pabawi_ldap_mapping_insert(); + +CREATE FUNCTION pabawi_ldap_mapping_update() RETURNS trigger LANGUAGE plpgsql AS $$ +BEGIN + UPDATE ldap_directory_state SET mapping_revision = mapping_revision + 1 + WHERE directory_id IN (SELECT OLD.directory_id UNION SELECT NEW.directory_id); + UPDATE ldap_validation_state SET last_validated_at = NULL + WHERE identity_id IN (SELECT identity_id FROM ldap_identity_metadata WHERE directory_id IN (SELECT OLD.directory_id UNION SELECT NEW.directory_id)); + UPDATE authorization_state SET revision = replace(gen_random_uuid()::text, '-', '') WHERE id = 1; + RETURN NULL; +END; +$$; +CREATE TRIGGER ldap_mapping_update AFTER UPDATE ON external_group_mappings +FOR EACH ROW EXECUTE FUNCTION pabawi_ldap_mapping_update(); + +-- PostgreSQL checks composite foreign keys before AFTER UPDATE withdrawal. +CREATE FUNCTION pabawi_ldap_mapping_withdraw() RETURNS trigger LANGUAGE plpgsql AS $$ +BEGIN + DELETE FROM federated_user_roles WHERE mapping_id = OLD.id; + RETURN NEW; +END; +$$; +CREATE TRIGGER ldap_mapping_withdraw BEFORE UPDATE ON external_group_mappings +FOR EACH ROW EXECUTE FUNCTION pabawi_ldap_mapping_withdraw(); + +CREATE FUNCTION pabawi_ldap_mapping_delete() RETURNS trigger LANGUAGE plpgsql AS $$ +BEGIN + UPDATE ldap_directory_state SET mapping_revision = mapping_revision + 1 + WHERE directory_id IN (SELECT OLD.directory_id); + UPDATE ldap_validation_state SET last_validated_at = NULL + WHERE identity_id IN (SELECT identity_id FROM ldap_identity_metadata WHERE directory_id IN (SELECT OLD.directory_id)); + UPDATE authorization_state SET revision = replace(gen_random_uuid()::text, '-', '') WHERE id = 1; + RETURN NULL; +END; +$$; +CREATE TRIGGER ldap_mapping_delete AFTER DELETE ON external_group_mappings +FOR EACH ROW EXECUTE FUNCTION pabawi_ldap_mapping_delete(); diff --git a/backend/src/database/migrations/031_external_identity_boundaries.sqlite.sql b/backend/src/database/migrations/031_external_identity_boundaries.sqlite.sql new file mode 100644 index 00000000..6959fe15 --- /dev/null +++ b/backend/src/database/migrations/031_external_identity_boundaries.sqlite.sql @@ -0,0 +1,232 @@ +-- pabawi:sqlite-foreign-keys-off +-- Preserve account IDs, session versions, and all referencing rows during rebuilds. +DROP VIEW effective_user_roles; +-- pabawi:statement-breakpoint +CREATE TABLE users_new ( + id TEXT PRIMARY KEY, + username TEXT NOT NULL UNIQUE, + email TEXT, + password_hash TEXT, + local_auth_enabled INTEGER NOT NULL DEFAULT 1 CHECK (local_auth_enabled IN (0, 1)), + display_name TEXT, + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + is_active INTEGER NOT NULL DEFAULT 1, + is_admin INTEGER NOT NULL DEFAULT 0, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + last_login_at TEXT, + session_version TEXT NOT NULL DEFAULT '0', + CHECK (local_auth_enabled = 0 OR (email IS NOT NULL AND length(trim(email)) > 0)), + CHECK (local_auth_enabled = 1 OR password_hash IS NULL) +); +-- pabawi:statement-breakpoint +INSERT INTO users_new (id, username, email, password_hash, local_auth_enabled, first_name, last_name, + is_active, is_admin, created_at, updated_at, last_login_at, session_version) +SELECT id, username, email, password_hash, CASE WHEN password_hash IS NULL THEN 0 ELSE 1 END, + first_name, last_name, is_active, is_admin, created_at, updated_at, last_login_at, session_version FROM users; +-- pabawi:statement-breakpoint +DROP TABLE users; +-- pabawi:statement-breakpoint +ALTER TABLE users_new RENAME TO users; +-- pabawi:statement-breakpoint +CREATE INDEX idx_users_username ON users(username); +-- pabawi:statement-breakpoint +CREATE INDEX idx_users_email ON users(email); +-- pabawi:statement-breakpoint +CREATE INDEX idx_users_active ON users(is_active); +-- pabawi:statement-breakpoint +CREATE TABLE federated_identities_new ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE, + provider TEXT NOT NULL, + subject TEXT NOT NULL, + issuer TEXT NOT NULL, + email TEXT, + id_token TEXT, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + UNIQUE(provider, issuer, subject), + UNIQUE(id, user_id), + UNIQUE(id, provider, issuer) +); +-- pabawi:statement-breakpoint +INSERT INTO federated_identities_new SELECT * FROM federated_identities; +-- pabawi:statement-breakpoint +DROP TABLE federated_identities; +-- pabawi:statement-breakpoint +ALTER TABLE federated_identities_new RENAME TO federated_identities; +-- pabawi:statement-breakpoint +CREATE INDEX idx_federated_identities_user ON federated_identities(user_id); +-- pabawi:statement-breakpoint +CREATE INDEX idx_federated_identities_lookup ON federated_identities(provider, issuer, subject); +-- pabawi:statement-breakpoint +CREATE UNIQUE INDEX idx_users_local_email ON users(email) WHERE local_auth_enabled = 1; +-- pabawi:statement-breakpoint +CREATE TABLE ldap_directory_state ( + directory_id TEXT PRIMARY KEY, + mapping_revision BIGINT NOT NULL DEFAULT 0 CHECK (mapping_revision >= 0), + config_revision TEXT NOT NULL DEFAULT '' +); +-- pabawi:statement-breakpoint +CREATE TABLE ldap_identity_metadata ( + identity_id TEXT PRIMARY KEY, + provider TEXT NOT NULL DEFAULT 'ldap' CHECK (provider = 'ldap'), + directory_id TEXT NOT NULL REFERENCES ldap_directory_state(directory_id), + login_name TEXT NOT NULL, + dn TEXT NOT NULL, + FOREIGN KEY (identity_id, provider, directory_id) + REFERENCES federated_identities(id, provider, issuer) ON DELETE CASCADE +); +-- pabawi:statement-breakpoint +CREATE INDEX idx_ldap_identity_directory ON ldap_identity_metadata(directory_id); +-- pabawi:statement-breakpoint +CREATE UNIQUE INDEX idx_ldap_identity_scope ON ldap_identity_metadata(identity_id, directory_id); +-- pabawi:statement-breakpoint +CREATE TABLE external_group_mappings ( + id TEXT PRIMARY KEY, + directory_id TEXT NOT NULL REFERENCES ldap_directory_state(directory_id), + group_subject TEXT NOT NULL, + group_dn TEXT NOT NULL, + group_name TEXT NOT NULL, + role_id TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE, + enabled INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0, 1)), + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + UNIQUE(directory_id, group_subject, role_id), + UNIQUE(id, role_id, directory_id) +); +-- pabawi:statement-breakpoint +CREATE TABLE federated_user_roles_new ( + user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE, + role_id TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE, + identity_id TEXT NOT NULL, + source_key TEXT NOT NULL CHECK (length(source_key) > 0), + mapping_id TEXT, + directory_id TEXT, + PRIMARY KEY (identity_id, role_id, source_key), + FOREIGN KEY (identity_id, user_id) REFERENCES federated_identities(id, user_id) ON DELETE CASCADE, + FOREIGN KEY (identity_id, directory_id) REFERENCES ldap_identity_metadata(identity_id, directory_id) ON DELETE CASCADE, + FOREIGN KEY (mapping_id, role_id, directory_id) REFERENCES external_group_mappings(id, role_id, directory_id) ON DELETE CASCADE, + CHECK ((mapping_id IS NULL AND directory_id IS NULL) OR (mapping_id IS NOT NULL AND directory_id IS NOT NULL)) +); +-- pabawi:statement-breakpoint +-- Detached historical grants have no provable identity owner. Preserve access. +INSERT INTO user_roles (user_id, role_id, assigned_at) +SELECT f.user_id, f.role_id, CAST(CURRENT_TIMESTAMP AS TEXT) FROM federated_user_roles f +WHERE NOT EXISTS (SELECT 1 FROM federated_identities i WHERE i.user_id = f.user_id AND i.provider = 'entra-id') +ON CONFLICT(user_id, role_id) DO NOTHING; +-- pabawi:statement-breakpoint +INSERT INTO federated_user_roles_new (user_id, role_id, identity_id, source_key) +SELECT f.user_id, f.role_id, i.id, 'legacy' +FROM federated_user_roles f JOIN federated_identities i ON i.user_id = f.user_id AND i.provider = 'entra-id'; +-- pabawi:statement-breakpoint +DROP TABLE federated_user_roles; +-- pabawi:statement-breakpoint +ALTER TABLE federated_user_roles_new RENAME TO federated_user_roles; +-- pabawi:statement-breakpoint +CREATE INDEX idx_federated_roles_user ON federated_user_roles(user_id, role_id); +-- pabawi:statement-breakpoint +CREATE INDEX idx_federated_roles_mapping ON federated_user_roles(mapping_id); +-- pabawi:statement-breakpoint +CREATE UNIQUE INDEX idx_federated_roles_mapping_identity ON federated_user_roles(identity_id, mapping_id) WHERE mapping_id IS NOT NULL; +-- pabawi:statement-breakpoint +CREATE VIEW effective_user_roles AS +SELECT user_id, role_id FROM user_roles +UNION SELECT user_id, role_id FROM federated_user_roles; +-- pabawi:statement-breakpoint +CREATE TABLE ldap_validation_state ( + identity_id TEXT PRIMARY KEY REFERENCES ldap_identity_metadata(identity_id) ON DELETE CASCADE, + last_validated_at BIGINT, + validation_generation BIGINT NOT NULL DEFAULT 0 CHECK (validation_generation >= 0), + mapping_revision BIGINT NOT NULL DEFAULT 0 CHECK (mapping_revision >= 0), + config_revision TEXT NOT NULL, + CHECK (last_validated_at IS NULL OR last_validated_at >= 0) +); +-- pabawi:statement-breakpoint +CREATE TABLE ldap_validation_leases ( + identity_id TEXT PRIMARY KEY REFERENCES ldap_identity_metadata(identity_id) ON DELETE CASCADE, + lease_owner TEXT, + lease_expires_at BIGINT, + fencing_generation BIGINT NOT NULL DEFAULT 0 CHECK (fencing_generation >= 0), + CHECK ((lease_owner IS NULL AND lease_expires_at IS NULL) OR (lease_owner IS NOT NULL AND lease_expires_at IS NOT NULL)) +); +-- pabawi:statement-breakpoint +CREATE INDEX idx_ldap_lease_expiry ON ldap_validation_leases(lease_expires_at); +-- pabawi:statement-breakpoint +-- Explicit statement boundaries keep SQLite trigger bodies intact. +CREATE TRIGGER revoke_user_sessions AFTER UPDATE OF password_hash, is_active, is_admin ON users +WHEN NEW.password_hash IS NOT OLD.password_hash OR NEW.is_active IS NOT OLD.is_active OR NEW.is_admin IS NOT OLD.is_admin +BEGIN + UPDATE users SET session_version = lower(hex(randomblob(16))) WHERE id = NEW.id; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER authz_users_insert AFTER INSERT ON users +BEGIN + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER authz_users_update AFTER UPDATE OF is_active, is_admin ON users +BEGIN + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER authz_users_delete AFTER DELETE ON users +BEGIN + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER authz_federated_roles_insert AFTER INSERT ON federated_user_roles +BEGIN + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER authz_federated_roles_update AFTER UPDATE ON federated_user_roles +BEGIN + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER authz_federated_roles_delete AFTER DELETE ON federated_user_roles +BEGIN + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER revoke_local_scope_sessions AFTER UPDATE OF local_auth_enabled ON users +WHEN NEW.local_auth_enabled IS NOT OLD.local_auth_enabled +BEGIN + UPDATE users SET session_version = lower(hex(randomblob(16))) WHERE id = NEW.id; +END; + +-- pabawi:statement-breakpoint +CREATE TRIGGER ldap_mapping_insert AFTER INSERT ON external_group_mappings +BEGIN + UPDATE ldap_directory_state SET mapping_revision = mapping_revision + 1 + WHERE directory_id IN (SELECT NEW.directory_id); + UPDATE ldap_validation_state SET last_validated_at = NULL + WHERE identity_id IN (SELECT identity_id FROM ldap_identity_metadata WHERE directory_id IN (SELECT NEW.directory_id)); + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER ldap_mapping_update AFTER UPDATE ON external_group_mappings +BEGIN + UPDATE ldap_directory_state SET mapping_revision = mapping_revision + 1 + WHERE directory_id IN (SELECT OLD.directory_id UNION SELECT NEW.directory_id); + UPDATE ldap_validation_state SET last_validated_at = NULL + WHERE identity_id IN (SELECT identity_id FROM ldap_identity_metadata WHERE directory_id IN (SELECT OLD.directory_id UNION SELECT NEW.directory_id)); + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; +-- pabawi:statement-breakpoint +-- Withdraw before a role/scope edit changes the referenced composite key. +CREATE TRIGGER ldap_mapping_withdraw BEFORE UPDATE ON external_group_mappings +BEGIN + DELETE FROM federated_user_roles WHERE mapping_id = OLD.id; +END; +-- pabawi:statement-breakpoint +CREATE TRIGGER ldap_mapping_delete AFTER DELETE ON external_group_mappings +BEGIN + UPDATE ldap_directory_state SET mapping_revision = mapping_revision + 1 + WHERE directory_id IN (SELECT OLD.directory_id); + UPDATE ldap_validation_state SET last_validated_at = NULL + WHERE identity_id IN (SELECT identity_id FROM ldap_identity_metadata WHERE directory_id IN (SELECT OLD.directory_id)); + UPDATE authorization_state SET revision = lower(hex(randomblob(16))) WHERE id = 1; +END; diff --git a/backend/src/services/AuthenticationService.ts b/backend/src/services/AuthenticationService.ts index 609a1599..4cf96b23 100644 --- a/backend/src/services/AuthenticationService.ts +++ b/backend/src/services/AuthenticationService.ts @@ -37,7 +37,8 @@ export interface TokenPayload { export interface UserDTO { id: string; username: string; - email: string; + email: string | null; + displayName: string | null; firstName: string; lastName: string; isActive: boolean; @@ -53,8 +54,9 @@ export interface UserDTO { interface User { id: string; username: string; - email: string; - passwordHash: string; + email: string | null; + displayName: string | null; + passwordHash: string | null; sessionVersion: string; firstName: string; lastName: string; @@ -513,8 +515,8 @@ export class AuthenticationService { * @param hash - Bcrypt hash * @returns True if password matches hash */ - public async comparePassword(password: string, hash: string): Promise { - return bcrypt.compare(password, hash); + public async comparePassword(password: string, hash: string | null): Promise { + return hash === null ? false : bcrypt.compare(password, hash); } /** @@ -524,7 +526,7 @@ export class AuthenticationService { * @param hash - Bcrypt hash * @returns True if password matches hash */ - public async verifyPassword(password: string, hash: string): Promise { + public async verifyPassword(password: string, hash: string | null): Promise { return this.comparePassword(password, hash); } @@ -631,6 +633,7 @@ export class AuthenticationService { return this.db.queryOne( `SELECT id, username, email, password_hash AS "passwordHash", + display_name AS "displayName", session_version AS "sessionVersion", first_name AS "firstName", last_name AS "lastName", @@ -639,7 +642,7 @@ export class AuthenticationService { created_at AS "createdAt", updated_at AS "updatedAt", last_login_at AS "lastLoginAt" - FROM users WHERE username = ?`, + FROM users WHERE username = ? AND local_auth_enabled = 1`, [username] ); } @@ -651,6 +654,7 @@ export class AuthenticationService { return this.db.queryOne( `SELECT id, username, email, password_hash AS "passwordHash", + display_name AS "displayName", session_version AS "sessionVersion", first_name AS "firstName", last_name AS "lastName", @@ -1018,6 +1022,7 @@ export class AuthenticationService { id: user.id, username: user.username, email: user.email, + displayName: user.displayName, firstName: user.firstName, lastName: user.lastName, isActive: user.isActive === 1, diff --git a/backend/src/services/EntraIdService.ts b/backend/src/services/EntraIdService.ts index 8fcd04dd..7c51ccd1 100644 --- a/backend/src/services/EntraIdService.ts +++ b/backend/src/services/EntraIdService.ts @@ -277,7 +277,12 @@ export class EntraIdService { const user = await this.provisionUser(claims); // 9. Sync group-to-role mapping - await this.syncGroupRoles(user.id, claims.groupsUnavailable ? [] : claims.groups); + const identity = await this.db.queryOne<{ id: string }>( + 'SELECT id FROM federated_identities WHERE user_id = ? AND provider = ? AND issuer = ? AND subject = ?', + [user.id, 'entra-id', claims.iss, claims.sub], + ); + if (!identity) throw new EntraIdError(ENTRA_ID_ERROR_CODES.PROVISIONING_FAILED, 'Authenticating identity is missing'); + await this.syncGroupRoles(identity.id, claims.groupsUnavailable ? [] : claims.groups); if (claims.groupsUnavailable && this.config.groupMapping) { throw new EntraIdError(ENTRA_ID_ERROR_CODES.GROUPS_UNAVAILABLE, "Complete group membership is required for login"); } @@ -334,7 +339,7 @@ export class EntraIdService { return existingUser; } - if (claims.email && await this.userService.findByEmail(claims.email)) { + if (claims.email && (await this.userService.findAllByEmail(claims.email)).length > 0) { const winner = await this.userService.findByFederatedIdentity('entra-id', claims.sub, claims.iss); if (winner) { this.requireActiveUser(winner); @@ -784,20 +789,26 @@ export class EntraIdService { } /** Replace only provider-owned grants, including grants from removed mappings. */ - async syncGroupRoles(userId: string, groups: string[] | undefined): Promise { + async syncGroupRoles(identityId: string, groups: string[] | undefined): Promise { await this.db.withTransaction(async () => { + const identity = await this.db.queryOne<{ userId: string }>( + `SELECT user_id AS "userId" FROM federated_identities WHERE id = ? AND provider = 'entra-id' AND issuer = ?`, + [identityId, `https://login.microsoftonline.com/${this.config.tenantId}/v2.0`], + ); + if (!identity) throw new EntraIdError(ENTRA_ID_ERROR_CODES.PROVISIONING_FAILED, 'Authenticating identity is missing'); + const { userId } = identity; // Serialize reconciliation of this account across PostgreSQL connections. await this.db.execute('UPDATE users SET updated_at = updated_at WHERE id = ?', [userId]); await this.db.execute(`DELETE FROM user_roles WHERE user_id = ? AND role_id IN (SELECT role_id FROM legacy_federated_user_roles WHERE user_id = ?)`, [userId, userId]); - await this.db.execute('DELETE FROM federated_user_roles WHERE user_id = ?', [userId]); + await this.db.execute('DELETE FROM federated_user_roles WHERE identity_id = ?', [identityId]); const normalizedGroups = new Set((groups ?? []).map(group => group.toLowerCase())); for (const [group, roleName] of Object.entries(this.config.groupMapping ?? {})) { if (!normalizedGroups.has(group.toLowerCase())) continue; const role = await this.db.queryOne<{ id: string }>('SELECT id FROM roles WHERE LOWER(name) = LOWER(?)', [roleName]); if (!role) throw new EntraIdError(ENTRA_ID_ERROR_CODES.PROVISIONING_FAILED, 'Group mapping references an unknown role'); - await this.db.execute(`INSERT INTO federated_user_roles (user_id, role_id) VALUES (?, ?) - ON CONFLICT(user_id, role_id) DO NOTHING`, [userId, role.id]); + await this.db.execute(`INSERT INTO federated_user_roles (user_id, role_id, identity_id, source_key) VALUES (?, ?, ?, ?) + ON CONFLICT(identity_id, role_id, source_key) DO NOTHING`, [userId, role.id, identityId, `group:${group.toLowerCase()}`]); } }); } diff --git a/backend/src/services/GroupService.ts b/backend/src/services/GroupService.ts index 2e1e90bd..fd0fbdee 100644 --- a/backend/src/services/GroupService.ts +++ b/backend/src/services/GroupService.ts @@ -74,7 +74,7 @@ export interface PaginatedResult { export interface User { id: string; username: string; - email: string; + email: string | null; firstName: string; lastName: string; isActive: number; diff --git a/backend/src/services/UserService.ts b/backend/src/services/UserService.ts index a82a8d32..27441c5e 100644 --- a/backend/src/services/UserService.ts +++ b/backend/src/services/UserService.ts @@ -11,8 +11,10 @@ import type { IdTokenClaims } from './EntraIdService'; export interface User { id: string; username: string; - email: string; - passwordHash: string; + email: string | null; + passwordHash: string | null; + localAuthEnabled: number; + displayName: string | null; firstName: string; lastName: string; isActive: number; @@ -32,6 +34,8 @@ export interface User { */ const USER_COLUMNS = `id, username, email, password_hash AS "passwordHash", + local_auth_enabled AS "localAuthEnabled", + display_name AS "displayName", first_name AS "firstName", last_name AS "lastName", is_active AS "isActive", @@ -65,7 +69,8 @@ const FEDERATED_IDENTITY_COLUMNS = `id, export interface UserDTO { id: string; username: string; - email: string; + email: string | null; + displayName: string | null; firstName: string; lastName: string; isActive: boolean; @@ -188,6 +193,9 @@ export class UserService { * @throws Error if username or email already exists */ public async createUser(data: CreateUserDTO): Promise { + if (data.username.toLowerCase().startsWith('ldap:')) { + throw new Error('Username uses a reserved directory namespace'); + } // Validate username uniqueness const existingUsername = await this.getUserByUsername(data.username); if (existingUsername) { @@ -195,7 +203,7 @@ export class UserService { } // Validate email uniqueness - const existingEmail = await this.getUserByEmail(data.email); + const existingEmail = await this.findLocalByEmail(data.email); if (existingEmail) { throw new Error('Email already exists'); } @@ -280,14 +288,14 @@ export class UserService { } /** - * Get user by email + * Resolve only the unique local credential scope. * * @param email - Email address * @returns User or null if not found */ - private async getUserByEmail(email: string): Promise { + public async findLocalByEmail(email: string): Promise { return this.db.queryOne( - `SELECT ${USER_COLUMNS} FROM users WHERE email = ?`, + `SELECT ${USER_COLUMNS} FROM users WHERE email = ? AND local_auth_enabled = 1`, [email] ); } @@ -308,9 +316,9 @@ export class UserService { } // Validate email uniqueness if email is being updated - if (data.email && data.email !== user.email) { - const existingEmail = await this.getUserByEmail(data.email); - if (existingEmail) { + if (data.email && data.email !== user.email && user.localAuthEnabled === 1) { + const existingEmail = await this.findLocalByEmail(data.email); + if (existingEmail && existingEmail.id !== id) { throw new Error('Email already exists'); } } @@ -335,6 +343,15 @@ export class UserService { } if (data.password !== undefined) { + if (user.localAuthEnabled === 0) { + const entraIdentity = await this.db.queryOne<{ id: string }>( + `SELECT id FROM federated_identities WHERE user_id = ? AND provider = 'entra-id' + AND NOT EXISTS (SELECT 1 FROM federated_identities WHERE user_id = ? AND provider = 'ldap')`, + [id, id] + ); + if (!entraIdentity) throw new Error('Directory accounts cannot have local passwords'); + updates.push('local_auth_enabled = 1'); + } // Validate password complexity const passwordValidation = validatePassword(data.password); if (!passwordValidation.valid) { @@ -651,6 +668,7 @@ export class UserService { id: user.id, username: user.username, email: user.email, + displayName: user.displayName, firstName: user.firstName, lastName: user.lastName, isActive: user.isActive === 1, @@ -696,6 +714,8 @@ export class UserService { // Use a transaction to ensure atomicity — no partial records return this.db.withTransaction(async () => { + // Serialize Entra collision checks across PostgreSQL provisioning writers. + await this.db.execute("UPDATE config SET value = value WHERE key = 'default_new_user_role'"); // Check username uniqueness const existingUsername = await this.getUserByUsername(username); if (existingUsername) { @@ -706,8 +726,8 @@ export class UserService { // Check email uniqueness (a separate user with this email should not exist; // collisions must never implicitly link the existing account) - const existingEmail = await this.getUserByEmail(claims.email); - if (existingEmail) { + const existingEmails = claims.email ? await this.findAllByEmail(claims.email) : []; + if (existingEmails.length > 0) { throw new Error( `Account creation failed: email "${claims.email}" already exists` ); @@ -718,12 +738,12 @@ export class UserService { // Insert user with null password_hash (federation-only) await this.db.execute( - `INSERT INTO users (id, username, email, password_hash, first_name, last_name, is_active, is_admin, created_at, updated_at) - VALUES (?, ?, ?, NULL, ?, ?, 1, 0, ?, ?)`, + `INSERT INTO users (id, username, email, password_hash, local_auth_enabled, first_name, last_name, is_active, is_admin, created_at, updated_at) + VALUES (?, ?, ?, NULL, 0, ?, ?, 1, 0, ?, ?)`, [ userId, username, - claims.email, + claims.email || null, claims.given_name || '', claims.family_name || '', now, @@ -841,14 +861,13 @@ export class UserService { } /** - * Public wrapper around the private getUserByEmail method. - * Used by EntraIdService for email-match account linking during SSO. - * - * @param email - Email address to search for - * @returns User or null if not found + * External contact email is not an identity key. Callers must handle all matches. */ - public async findByEmail(email: string): Promise { - return this.getUserByEmail(email); + public async findAllByEmail(email: string): Promise { + return this.db.query( + `SELECT ${USER_COLUMNS} FROM users WHERE email = ? ORDER BY id`, + [email] + ); } } diff --git a/backend/test/UserService.password.test.ts b/backend/test/UserService.password.test.ts index 45199802..44c6ccf8 100644 --- a/backend/test/UserService.password.test.ts +++ b/backend/test/UserService.password.test.ts @@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest'; import { SQLiteAdapter } from '../src/database/SQLiteAdapter'; import { UserService } from '../src/services/UserService'; import { AuthenticationService } from '../src/services/AuthenticationService'; +import { initializeTestSchema } from './helpers/schema'; describe('UserService - Password Validation Integration', () => { let db: SQLiteAdapter; @@ -15,9 +16,7 @@ describe('UserService - Password Validation Integration', () => { await db.initialize(); // Initialize schema - await initializeSchema(db); - - await db.execute('CREATE VIEW effective_user_roles AS SELECT user_id, role_id FROM user_roles'); + await initializeTestSchema(db); authService = new AuthenticationService(db, testJwtSecret); userService = new UserService(db, authService); @@ -182,112 +181,3 @@ describe('UserService - Password Validation Integration', () => { }); }); }); - - -// Helper function to initialize database schema -async function initializeSchema(db: SQLiteAdapter): Promise { - const schema = ` - CREATE TABLE users ( - id TEXT PRIMARY KEY, - username TEXT NOT NULL UNIQUE, - email TEXT NOT NULL UNIQUE, - password_hash TEXT NOT NULL, - session_version TEXT NOT NULL DEFAULT '0', - first_name TEXT NOT NULL, - last_name TEXT NOT NULL, - is_active INTEGER NOT NULL DEFAULT 1, - is_admin INTEGER NOT NULL DEFAULT 0, - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL, - last_login_at TEXT - ); - - CREATE TABLE groups ( - id TEXT PRIMARY KEY, - name TEXT NOT NULL UNIQUE, - description TEXT NOT NULL, - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL - ); - - CREATE TABLE roles ( - id TEXT PRIMARY KEY, - name TEXT NOT NULL UNIQUE, - description TEXT NOT NULL, - is_built_in INTEGER NOT NULL DEFAULT 0, - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL - ); - - CREATE TABLE permissions ( - id TEXT PRIMARY KEY, - resource TEXT NOT NULL, - action TEXT NOT NULL, - description TEXT NOT NULL, - created_at TEXT NOT NULL, - UNIQUE(resource, action) - ); - - CREATE TABLE user_groups ( - user_id TEXT NOT NULL, - group_id TEXT NOT NULL, - assigned_at TEXT NOT NULL, - PRIMARY KEY (user_id, group_id), - FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, - FOREIGN KEY (group_id) REFERENCES groups(id) ON DELETE CASCADE - ); - - CREATE TABLE user_roles ( - user_id TEXT NOT NULL, - role_id TEXT NOT NULL, - assigned_at TEXT NOT NULL, - PRIMARY KEY (user_id, role_id), - FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, - FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE - ); - - CREATE TABLE group_roles ( - group_id TEXT NOT NULL, - role_id TEXT NOT NULL, - assigned_at TEXT NOT NULL, - PRIMARY KEY (group_id, role_id), - FOREIGN KEY (group_id) REFERENCES groups(id) ON DELETE CASCADE, - FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE - ); - - CREATE TABLE role_permissions ( - role_id TEXT NOT NULL, - permission_id TEXT NOT NULL, - assigned_at TEXT NOT NULL, - PRIMARY KEY (role_id, permission_id), - FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE, - FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE - ); - - CREATE TABLE revoked_tokens ( - token TEXT PRIMARY KEY, - user_id TEXT NOT NULL, - revoked_at TEXT NOT NULL, - expires_at TEXT NOT NULL, - FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE - ); - - CREATE TABLE config ( - key TEXT PRIMARY KEY, - value TEXT NOT NULL, - updated_at TEXT NOT NULL - ); - - INSERT INTO config (key, value, updated_at) VALUES - ('allow_self_registration', 'false', datetime('now')), - ('default_new_user_role', 'role-viewer-001', datetime('now')); - - INSERT INTO roles (id, name, description, is_built_in, created_at, updated_at) VALUES - ('role-viewer-001', 'Viewer', 'Default viewer role', 1, datetime('now'), datetime('now')); - `; - - const statements = schema.split(';').map(s => s.trim()).filter(s => s.length > 0); - for (const statement of statements) { - await db.execute(statement); - } -} diff --git a/backend/test/database/BatchLifecycleMigration.test.ts b/backend/test/database/BatchLifecycleMigration.test.ts index b0b124a6..6921a60c 100644 --- a/backend/test/database/BatchLifecycleMigration.test.ts +++ b/backend/test/database/BatchLifecycleMigration.test.ts @@ -42,7 +42,7 @@ for (const dialect of ['sqlite', 'postgres'] as const) { const batch = await db.queryOne>("SELECT * FROM batch_executions WHERE id = 'batch'"); const runner = new MigrationRunner(db, migrations); // Every migration from 029 onwards has to leave the populated history below intact. - expect(await runner.runPendingMigrations()).toBe(2); + expect(await runner.runPendingMigrations()).toBe(3); expect(await db.queryOne("SELECT * FROM executions WHERE id = 'child'")).toMatchObject({ ...original, created_at: original!.started_at, user_id: 'actor', cancellation_requested_at: null, }); diff --git a/backend/test/database/external-identity-boundaries.test.ts b/backend/test/database/external-identity-boundaries.test.ts new file mode 100644 index 00000000..8ab8ca76 --- /dev/null +++ b/backend/test/database/external-identity-boundaries.test.ts @@ -0,0 +1,348 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { randomUUID } from 'node:crypto'; +import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, rmSync, readFileSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { DatabaseService } from '../../src/database/DatabaseService'; +import { SQLiteAdapter } from '../../src/database/SQLiteAdapter'; +import { PostgresAdapter } from '../../src/database/PostgresAdapter'; +import { MigrationRunner } from '../../src/database/MigrationRunner'; +import type { DatabaseAdapter } from '../../src/database/DatabaseAdapter'; +import { UserService } from '../../src/services/UserService'; +import { AuthenticationService } from '../../src/services/AuthenticationService'; +import { PermissionService } from '../../src/services/PermissionService'; +import { EntraIdService, type IdTokenClaims } from '../../src/services/EntraIdService'; +import { RoleService } from '../../src/services/RoleService'; +import { AuditLoggingService } from '../../src/services/AuditLoggingService'; +import { LoggerService } from '../../src/services/LoggerService'; + +const migrations = join(__dirname, '../../src/database/migrations'); +const databaseUrl = process.env.TEST_DATABASE_URL; +const issuer = 'https://login.microsoftonline.com/tenant/v2.0'; +const fixturePassword = 'ValidPass123!'; // pragma: allowlist secret +const fixtureClientSecret = 'fixture'; // pragma: allowlist secret +const claims: IdTokenClaims = { sub: 'subject', iss: issuer, aud: 'client', exp: 9999999999, + nonce: 'nonce', email: 'entra@example.test', preferred_username: 'entrauser', given_name: 'Entra', family_name: 'User' }; + +async function externalUser(db: DatabaseAdapter, id: string, email: string | null = null): Promise { + await db.execute(`INSERT INTO users + (id, username, email, password_hash, local_auth_enabled, first_name, last_name, created_at, updated_at) + VALUES (?, ?, ?, NULL, 0, '', '', 'now', 'now')`, [id, `ldap:${id}`, email]); +} + +async function identity(db: DatabaseAdapter, id: string, user: string, provider = 'ldap', scope = 'directory'): Promise { + await db.execute(`INSERT INTO federated_identities (id, user_id, provider, issuer, subject, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, 'now', 'now')`, [id, user, provider, scope, id]); +} + +async function ldapIdentity(db: DatabaseAdapter, id = 'ldap', user = 'external'): Promise { + await identity(db, id, user); + await db.execute(`INSERT INTO ldap_directory_state (directory_id) VALUES ('directory') ON CONFLICT DO NOTHING`); + await db.execute(`INSERT INTO ldap_identity_metadata (identity_id, directory_id, login_name, dn) + VALUES (?, 'directory', 'login', 'uid=login,dc=example')`, [id]); +} + +async function mapping(db: DatabaseAdapter, id: string): Promise { + await db.execute(`INSERT INTO external_group_mappings + (id, directory_id, group_subject, group_dn, group_name, role_id, created_at, updated_at) + VALUES (?, 'directory', ?, ?, ?, 'role-viewer-001', 'now', 'now')`, [id, id, `cn=${id},dc=example`, id]); +} + +async function grant(db: DatabaseAdapter, mappingId: string): Promise { + await db.execute(`INSERT INTO federated_user_roles (user_id, role_id, identity_id, source_key, mapping_id, directory_id) + VALUES ('external', 'role-viewer-001', 'ldap', ?, ?, 'directory')`, [`mapping:${mappingId}`, mappingId]); +} + +for (const dialect of ['sqlite', 'postgres'] as const) { + describe.skipIf(dialect === 'postgres' && !databaseUrl)(`${dialect}: external identity boundaries`, () => { + let dir: string; + let url: string; + let control: PostgresAdapter | undefined; + let database: DatabaseService; + let db: DatabaseAdapter; + let reader: DatabaseAdapter; + let users: UserService; + let auth: AuthenticationService; + let entra: EntraIdService; + let schema: string; + + beforeEach(async () => { + dir = mkdtempSync(join(tmpdir(), 'pabawi-ldap-schema-')); + schema = `ldap_${randomUUID().replaceAll('-', '')}`; + url = ''; + if (dialect === 'postgres' && databaseUrl) { + control = new PostgresAdapter(databaseUrl); + await control.initialize(); + await control.execute(`CREATE SCHEMA ${schema}`); + const scoped = new URL(databaseUrl); + scoped.searchParams.set('options', `-csearch_path=${schema}`); + url = scoped.toString(); + } + database = new DatabaseService(join(dir, 'live.db'), dialect, url); + await database.initialize(); + db = database.getAdapter(); + reader = dialect === 'sqlite' ? new SQLiteAdapter(join(dir, 'live.db')) : new PostgresAdapter(url); + await reader.initialize(); + auth = new AuthenticationService(db, 'external-identity-fixture-secret'); + users = new UserService(db, auth); + entra = new EntraIdService(db, { enabled: true, tenantId: 'tenant', clientId: 'client', clientSecret: fixtureClientSecret, + redirectUri: 'http://localhost/callback', scopes: ['openid'], groupMapping: { A: 'Viewer', B: 'Viewer' }, jwksCacheTtlMs: 1000 }, + auth, users, new RoleService(db), new AuditLoggingService(db), new LoggerService()); + }); + + afterEach(async () => { + await reader?.close(); + await database?.close(); + if (control) { + await control.execute(`DROP SCHEMA ${schema} CASCADE`); + await control.close(); + control = undefined; + } + rmSync(dir, { recursive: true, force: true }); + }); + + it('allows null and duplicate external emails while local lookup and uniqueness remain unambiguous', async () => { + await externalUser(db, 'one'); + await externalUser(db, 'two'); + await externalUser(db, 'three', 'shared@example.test'); + await externalUser(db, 'four', 'shared@example.test'); + expect((await users.getUserById('one'))?.passwordHash).toBeNull(); + expect(users.toUserDTO((await users.getUserById('one'))!).email).toBeNull(); + expect(await users.findLocalByEmail('shared@example.test')).toBeNull(); + const local = await users.createUser({ username: 'local', email: 'shared@example.test', password: fixturePassword, firstName: 'Local', lastName: 'User' }); + expect((await users.findLocalByEmail('shared@example.test'))?.id).toBe(local.id); + expect(await users.findAllByEmail('shared@example.test')).toHaveLength(3); + await expect(users.createUser({ username: 'another', email: 'shared@example.test', password: fixturePassword, firstName: '', lastName: '' })).rejects.toThrow('Email already exists'); + await expect(db.execute(`INSERT INTO users (id, username, email, first_name, last_name, created_at, updated_at) + VALUES ('duplicate', 'duplicate', 'shared@example.test', '', '', 'now', 'now')`)).rejects.toThrow(); + await expect(db.execute(`UPDATE users SET email = NULL WHERE id = ?`, [local.id])).rejects.toThrow(); + await expect(db.execute(`UPDATE users SET password_hash = ? WHERE id = 'one'`, ['hash'])).rejects.toThrow(); + expect((await auth.authenticate('local', fixturePassword)).success).toBe(true); + expect((await auth.authenticate('ldap:one', fixturePassword)).success).toBe(false); + await expect(users.createUser({ username: 'LDAP:reserved', email: 'reserved@example.test', password: fixturePassword, firstName: '', lastName: '' })).rejects.toThrow('reserved'); + }); + + it('preserves Entra collision rejection with any email match and permits missing contact email', async () => { + await externalUser(db, 'one', claims.email); + await externalUser(db, 'two', claims.email); + await expect(entra.provisionUser(claims)).rejects.toMatchObject({ code: 'IDENTITY_COLLISION' }); + expect(await db.query('SELECT id FROM federated_identities')).toEqual([]); + for (const name of ['first', 'second']) { + const user = await entra.provisionUser({ ...claims, sub: name, email: '', preferred_username: name }); + expect(user.email).toBeNull(); + expect(user.localAuthEnabled).toBe(0); + expect(await users.getUserRoles(user.id)).toHaveLength(1); + } + }); + + it('keys identities by provider, issuer and subject and preserves identity during locator changes', async () => { + await externalUser(db, 'external'); + await ldapIdentity(db); + await identity(db, 'other', 'external', 'ldap', 'other-directory'); + await db.execute(`UPDATE federated_identities SET subject = 'ldap' WHERE id = 'other'`); + await expect(identity(db, 'third', 'external')).resolves.toBeUndefined(); + await expect(db.execute(`UPDATE federated_identities SET subject = 'ldap' WHERE id = 'third'`)).rejects.toThrow(); + expect((await users.findByFederatedIdentity('ldap', 'ldap', 'directory'))?.id).toBe('external'); + const token = await auth.generateToken({ id: 'external', username: 'ldap:external' }); + await db.execute(`UPDATE ldap_identity_metadata SET login_name = 'renamed', dn = 'uid=renamed,ou=moved,dc=example' WHERE identity_id = 'ldap'`); + await db.execute(`UPDATE users SET display_name = 'Single Display Name', first_name = '', last_name = '', email = NULL, updated_at = 'later' WHERE id = 'external'`); + expect((await auth.verifyToken(token)).userId).toBe('external'); + expect((await users.getUserById('external'))?.displayName).toBe('Single Display Name'); + await externalUser(db, 'replacement'); + await ldapIdentity(db, 'new-object', 'replacement'); + expect((await users.findByFederatedIdentity('ldap', 'new-object', 'directory'))?.id).toBe('replacement'); + await expect(db.execute(`UPDATE ldap_identity_metadata SET directory_id = 'other-directory' WHERE identity_id = 'ldap'`)).rejects.toThrow(); + }); + + it('preserves explicit Entra password administration and rejects local credentials for LDAP identities', async () => { + const user = await entra.provisionUser(claims); + expect((await auth.authenticate(user.username, fixturePassword)).success).toBe(false); + await users.updateUser(user.id, { password: fixturePassword }); + expect((await users.getUserById(user.id))?.localAuthEnabled).toBe(1); + expect((await auth.authenticate(user.username, fixturePassword)).success).toBe(true); + expect((await entra.provisionUser(claims)).id).toBe(user.id); + await externalUser(db, 'external'); + await ldapIdentity(db); + await expect(users.updateUser('external', { password: fixturePassword })).rejects.toThrow('cannot have local passwords'); + expect((await users.getUserById('external'))?.passwordHash).toBeNull(); + const { refreshToken } = await auth.generateTokenPair({ id: 'external', username: 'ldap:external' }); + expect((await auth.refreshToken(refreshToken)).user?.email).toBeNull(); + }); + + it('serializes concurrent Entra email collision checks after removal of the global email index', async () => { + const readerAuth = new AuthenticationService(reader, 'external-identity-fixture-secret'); + const otherEntra = new EntraIdService(reader, { enabled: true, tenantId: 'tenant', clientId: 'client', clientSecret: fixtureClientSecret, + redirectUri: 'http://localhost/callback', scopes: ['openid'], groupMapping: null, jwksCacheTtlMs: 1000 }, + readerAuth, new UserService(reader, readerAuth), new RoleService(reader), new AuditLoggingService(reader), new LoggerService()); + const results = await Promise.allSettled([entra, otherEntra].map((service, index) => service.provisionUser({ + ...claims, sub: `subject-${String(index)}`, preferred_username: `user_${String(index)}`, + }))); + expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1); + expect(results.filter(result => result.status === 'rejected')).toHaveLength(1); + expect(await users.findAllByEmail(claims.email)).toHaveLength(1); + expect(await db.query('SELECT id FROM federated_identities')).toHaveLength(1); + }); + + it('deduplicates effective roles while preserving mapping, manual and other identity provenance', async () => { + await externalUser(db, 'external'); + await ldapIdentity(db); + await identity(db, 'entra', 'external', 'entra-id', issuer); + await identity(db, 'another-entra', 'external', 'entra-id', issuer); + await db.execute(`INSERT INTO federated_user_roles (user_id, role_id, identity_id, source_key) + VALUES ('external', 'role-viewer-001', 'another-entra', 'other-source')`); + await mapping(db, 'one'); + await mapping(db, 'two'); + await grant(db, 'one'); + await grant(db, 'two'); + await entra.syncGroupRoles('entra', ['A', 'B']); + expect(await db.query('SELECT * FROM federated_user_roles')).toHaveLength(5); + expect(await users.getUserRoles('external')).toHaveLength(1); + await entra.syncGroupRoles('entra', []); + expect(await db.query('SELECT * FROM federated_user_roles')).toHaveLength(3); + await db.execute(`INSERT INTO user_roles VALUES ('external', 'role-viewer-001', 'now')`); + const permissions = new PermissionService(reader); + expect(await permissions.hasPermission('external', 'executions', 'read')).toBe(true); + await db.execute(`DELETE FROM external_group_mappings WHERE id = 'one'`); + expect(await db.query(`SELECT mapping_id FROM federated_user_roles WHERE identity_id = 'ldap'`)).toEqual([{ mapping_id: 'two' }]); + expect(await permissions.hasPermission('external', 'executions', 'read')).toBe(true); + await db.execute(`UPDATE external_group_mappings SET enabled = 0 WHERE id = 'two'`); + expect(await db.query(`SELECT * FROM federated_user_roles WHERE identity_id = 'ldap'`)).toEqual([]); + await db.execute(`DELETE FROM federated_identities WHERE id = 'another-entra'`); + expect(await permissions.hasPermission('external', 'executions', 'read')).toBe(true); + await db.execute(`DELETE FROM user_roles WHERE user_id = 'external'`); + expect(await permissions.hasPermission('external', 'executions', 'read')).toBe(false); + await expect(entra.syncGroupRoles('ldap', ['A'])).rejects.toThrow('identity is missing'); + }); + + it('enforces grant ownership and invalidates persisted validation on mapping changes across connections', async () => { + await externalUser(db, 'external'); + await externalUser(db, 'other-user'); + await ldapIdentity(db); + await mapping(db, 'one'); + await grant(db, 'one'); + await db.execute(`INSERT INTO ldap_validation_state + (identity_id, last_validated_at, validation_generation, mapping_revision, config_revision) + VALUES ('ldap', 1000, 3, 1, 'config')`); + await db.execute(`INSERT INTO ldap_validation_leases (identity_id, lease_owner, lease_expires_at, fencing_generation) + VALUES ('ldap', 'process', 2000, 4)`); + await expect(db.execute(`UPDATE federated_user_roles SET user_id = 'other-user'`)).rejects.toThrow(); + await expect(db.execute(`UPDATE federated_user_roles SET directory_id = 'other-directory'`)).rejects.toThrow(); + const before = await reader.queryOne<{ revision: string }>('SELECT revision FROM authorization_state'); + await db.execute(`UPDATE external_group_mappings SET group_dn = 'cn=moved,dc=example' WHERE id = 'one'`); + expect(String((await reader.queryOne<{ mapping_revision: string }>('SELECT mapping_revision FROM ldap_directory_state'))?.mapping_revision)).toBe('2'); + expect(await reader.queryOne('SELECT last_validated_at FROM ldap_validation_state')).toEqual({ last_validated_at: null }); + expect(await reader.queryOne('SELECT revision FROM authorization_state')).not.toEqual(before); + expect(await reader.query('SELECT * FROM federated_user_roles')).toEqual([]); + await grant(db, 'one'); + await db.execute(`UPDATE external_group_mappings SET role_id = 'role-operator-001' WHERE id = 'one'`); + expect(await reader.query('SELECT * FROM federated_user_roles')).toEqual([]); + await expect(db.withTransaction(async () => { + await db.execute(`DELETE FROM external_group_mappings WHERE id = 'one'`); + throw new Error('rollback mapping'); + })).rejects.toThrow('rollback mapping'); + expect(String((await reader.queryOne<{ mapping_revision: string }>('SELECT mapping_revision FROM ldap_directory_state'))?.mapping_revision)).toBe('3'); + await db.execute(`DELETE FROM users WHERE id = 'external'`); + for (const table of ['federated_identities', 'ldap_identity_metadata', 'ldap_validation_state', 'ldap_validation_leases']) { + expect(await db.query(`SELECT * FROM ${table}`)).toEqual([]); + } + if (dialect === 'sqlite') expect(await db.query('PRAGMA foreign_key_check')).toEqual([]); + }); + + it('upgrades a populated migration-030 database without changing enrollments, sessions or relationships', async () => { + // Use a second isolated schema/file so the fixture really predates migration 031. + const partial = join(dir, 'migrations'); + mkdirSync(partial); + for (const file of readdirSync(migrations)) { + if (file.slice(0, 3) <= '030') copyFileSync(join(migrations, file), join(partial, file)); + } + const upgradeSchema = `${schema}_upgrade`; + if (control) await control.execute(`CREATE SCHEMA ${upgradeSchema}`); + const upgradeUrl = new URL(url || 'postgresql://localhost/unused'); + upgradeUrl.searchParams.set('options', `-csearch_path=${upgradeSchema}`); + const old = dialect === 'sqlite' ? new SQLiteAdapter(join(dir, 'upgrade.db')) : new PostgresAdapter(upgradeUrl.toString()); + await old.initialize(); + try { + await new MigrationRunner(old, partial).runPendingMigrations(); + for (const [id, password] of [['local', 'hash'], ['enrolled', 'hash'], ['federated', null], ['detached', null]]) { + await old.execute(`INSERT INTO users (id, username, email, password_hash, first_name, last_name, created_at, updated_at, session_version) + VALUES (?, ?, ?, ?, '', '', 'now', 'now', 'abc123')`, [id, id, `${id}@example.test`, password]); + } + for (const user of ['enrolled', 'federated']) { + await identity(old, `${user}-identity`, user, 'entra-id', issuer); + await old.execute(`INSERT INTO federated_user_roles VALUES (?, 'role-viewer-001')`, [user]); + } + await old.execute(`INSERT INTO federated_user_roles VALUES ('detached', 'role-viewer-001')`); + await old.execute(`INSERT INTO user_roles VALUES ('enrolled', 'role-operator-001', 'now')`); + await old.execute(`INSERT INTO legacy_federated_user_roles VALUES ('enrolled', 'role-operator-001')`); + await old.execute(`INSERT INTO groups VALUES ('group', 'group', '', 'now', 'now')`); + await old.execute(`INSERT INTO user_groups VALUES ('enrolled', 'group', 'now')`); + await old.execute(`INSERT INTO revoked_tokens VALUES ('token', 'enrolled', 'now', 'later')`); + await old.execute(`INSERT INTO audit_logs (id, timestamp, event_type, "action", user_id, result) + VALUES ('audit', 'now', 'auth', 'login_success', 'enrolled', 'success')`); + await old.execute(`INSERT INTO journal_entries (id, node_id, node_uri, event_type, source, "action", summary, user_id, timestamp) + VALUES ('journal', 'n1', 'ssh://n1', 'note', 'user', 'note', 'fixture', 'enrolled', 'now')`); + const tables = ['federated_identities', 'user_groups', 'legacy_federated_user_roles', 'revoked_tokens', 'audit_logs', 'journal_entries']; + const before = await Promise.all(tables.map(table => old.query(`SELECT * FROM ${table}`))); + const accountColumns = 'id, username, email, password_hash, session_version, is_active, is_admin, first_name, last_name, created_at, updated_at, last_login_at'; + const accountsBefore = await old.query(`SELECT ${accountColumns} FROM users ORDER BY id`); + const permissionsBefore = await old.query('SELECT * FROM effective_user_roles ORDER BY user_id, role_id'); + await new MigrationRunner(old).runPendingMigrations(); + expect(await old.query(`SELECT ${accountColumns} FROM users ORDER BY id`)).toEqual(accountsBefore); + expect(await Promise.all(tables.map(table => old.query(`SELECT * FROM ${table}`)))).toEqual(before); + expect(await old.query('SELECT * FROM effective_user_roles ORDER BY user_id, role_id')).toEqual(permissionsBefore); + expect(await old.query('SELECT user_id, identity_id, source_key FROM federated_user_roles ORDER BY user_id')).toEqual([ + { user_id: 'enrolled', identity_id: 'enrolled-identity', source_key: 'legacy' }, + { user_id: 'federated', identity_id: 'federated-identity', source_key: 'legacy' }, + ]); + expect(await old.query('SELECT id, local_auth_enabled FROM users ORDER BY id')).toEqual([ + { id: 'detached', local_auth_enabled: 0 }, { id: 'enrolled', local_auth_enabled: 1 }, + { id: 'federated', local_auth_enabled: 0 }, { id: 'local', local_auth_enabled: 1 }, + ]); + const oldAuth = new AuthenticationService(old, 'upgrade-fixture-secret'); + const token = await oldAuth.generateToken({ id: 'enrolled', username: 'enrolled' }); + await old.execute(`UPDATE users SET display_name = 'Changed' WHERE id = 'enrolled'`); + await expect(oldAuth.verifyToken(token)).resolves.toBeDefined(); + await old.execute(`UPDATE users SET password_hash = ? WHERE id = 'enrolled'`, ['changed']); + await expect(oldAuth.verifyToken(token)).rejects.toThrow('revoked'); + expect((await new MigrationRunner(old).getStatus()).pending).toEqual([]); + if (dialect === 'sqlite') { + expect(await old.query('PRAGMA foreign_key_check')).toEqual([]); + expect(await old.query('PRAGMA integrity_check')).toEqual([{ integrity_check: 'ok' }]); + } + } finally { + await old.close(); + if (control) await control.execute(`DROP SCHEMA ${upgradeSchema} CASCADE`); + } + }); + }); +} + +describe('SQLite migration 031 rollback', () => { + it('restores the pre-upgrade schema and foreign keys after a rebuild fails', async () => { + const dir = mkdtempSync(join(tmpdir(), 'pabawi-ldap-rollback-')); + const db = new SQLiteAdapter(join(dir, 'live.db')); + await db.initialize(); + try { + for (const file of readdirSync(migrations)) { + if (file.slice(0, 3) <= '030') copyFileSync(join(migrations, file), join(dir, file)); + } + await new MigrationRunner(db, dir).runPendingMigrations(); + await db.execute(`INSERT INTO users (id, username, email, password_hash, first_name, last_name, created_at, updated_at) + VALUES ('user', 'user', 'user@example.test', 'hash', '', '', 'now', 'now')`); + await identity(db, 'entra', 'user', 'entra-id', issuer); + await db.execute(`INSERT INTO federated_user_roles VALUES ('user', 'role-viewer-001')`); + const filename = '031_external_identity_boundaries.sqlite.sql'; + writeFileSync(join(dir, filename), `${readFileSync(join(migrations, filename), 'utf8')}\n-- pabawi:statement-breakpoint\nINSERT INTO missing_table VALUES (1);`); + await expect(new MigrationRunner(db, dir).runPendingMigrations()).rejects.toThrow('missing_table'); + expect(await db.query('PRAGMA foreign_keys')).toEqual([{ foreign_keys: 1 }]); + expect(await db.query('SELECT * FROM effective_user_roles')).toEqual([{ user_id: 'user', role_id: 'role-viewer-001' }]); + expect(await db.query('SELECT * FROM federated_user_roles')).toEqual([{ user_id: 'user', role_id: 'role-viewer-001' }]); + expect(await db.query("SELECT * FROM migrations WHERE id = '031'")).toEqual([]); + await new MigrationRunner(db).runPendingMigrations(); + expect(await db.query('PRAGMA foreign_key_check')).toEqual([]); + } finally { + await db.close(); + rmSync(dir, { recursive: true, force: true }); + } + }); +}); diff --git a/backend/test/database/migration-integration.test.ts b/backend/test/database/migration-integration.test.ts index ba55483f..633735dd 100644 --- a/backend/test/database/migration-integration.test.ts +++ b/backend/test/database/migration-integration.test.ts @@ -28,8 +28,8 @@ describe('Migration Integration Test', () => { it('should apply all migrations on initialization', async () => { const status = await dbService.getMigrationStatus(); - // Should have applied all migrations (000 through 030, no 012 in source) - expect(status.applied).toHaveLength(30); + // Should have applied all migrations (000 through 031, no 012 in source) + expect(status.applied).toHaveLength(31); expect(status.applied[0].id).toBe('000'); expect(status.applied[1].id).toBe('001'); expect(status.applied[2].id).toBe('002'); @@ -52,7 +52,7 @@ describe('Migration Integration Test', () => { expect(status.applied[19].id).toBe('020'); expect(status.applied[20].id).toBe('021'); expect(status.applied[21].id).toBe('022'); - expect(status.applied.at(-1)?.id).toBe('030'); + expect(status.applied.at(-1)?.id).toBe('031'); expect(status.pending).toHaveLength(0); }); @@ -93,8 +93,8 @@ describe('Migration Integration Test', () => { const status = await dbService2.getMigrationStatus(); - // Should still have 30 applied, 0 pending - expect(status.applied).toHaveLength(30); + // Should still have 31 applied, 0 pending + expect(status.applied).toHaveLength(31); expect(status.pending).toHaveLength(0); await dbService2.close(); diff --git a/backend/test/database/rbac-schema.test.ts b/backend/test/database/rbac-schema.test.ts index 1b30ae6a..f5abece3 100644 --- a/backend/test/database/rbac-schema.test.ts +++ b/backend/test/database/rbac-schema.test.ts @@ -31,7 +31,10 @@ describe('RBAC Database Schema', () => { expect(result).toBeDefined(); expect(result.sql).toContain('id TEXT PRIMARY KEY'); expect(result.sql).toContain('username TEXT NOT NULL UNIQUE'); - expect(result.sql).toContain('email TEXT NOT NULL UNIQUE'); + expect(result.sql).toContain('email TEXT'); + expect(result.sql).toContain('local_auth_enabled INTEGER NOT NULL DEFAULT 1'); + const index = await db.queryOne<{ sql: string }>("SELECT sql FROM sqlite_master WHERE name = 'idx_users_local_email'"); + expect(index?.sql).toContain('UNIQUE INDEX idx_users_local_email ON users(email) WHERE local_auth_enabled = 1'); expect(result.sql).toContain('password_hash TEXT'); expect(result.sql).toContain('is_active INTEGER NOT NULL DEFAULT 1'); expect(result.sql).toContain('is_admin INTEGER NOT NULL DEFAULT 0'); diff --git a/backend/test/database/sso-concurrency.test.ts b/backend/test/database/sso-concurrency.test.ts index 01c3783c..5c61e3a9 100644 --- a/backend/test/database/sso-concurrency.test.ts +++ b/backend/test/database/sso-concurrency.test.ts @@ -48,11 +48,13 @@ for (const dialect of ['sqlite', 'postgres'] as const) { const users = await Promise.all(services.map(service => service.provisionUser(claims))); expect(new Set(users.map(user => user.id)).size).toBe(1); expect(await adapters[0].query('SELECT * FROM federated_identities')).toHaveLength(1); + const identity = await adapters[0].queryOne<{ id: string }>('SELECT id FROM federated_identities WHERE user_id = ?', [users[0].id]); + expect(identity).not.toBeNull(); await adapters[0].execute('DELETE FROM user_roles WHERE user_id = ?', [users[0].id]); const permissions = new PermissionService(adapters[1]); - await Promise.all(services.map(service => service.syncGroupRoles(users[0].id, ['a']))); + await Promise.all(services.map(service => service.syncGroupRoles(identity!.id, ['a']))); expect(await permissions.hasPermission(users[0].id, 'executions', 'read')).toBe(true); - await services[0].syncGroupRoles(users[0].id, undefined); + await services[0].syncGroupRoles(identity!.id, undefined); expect(await permissions.hasPermission(users[0].id, 'executions', 'read')).toBe(false); const { token, refreshToken } = await services[0].authService.generateTokenPair(users[0]); const binding = 'a'.repeat(64); diff --git a/backend/test/properties/EntraIdAuthCode.property.test.ts b/backend/test/properties/EntraIdAuthCode.property.test.ts index 3774558b..c4a6d034 100644 --- a/backend/test/properties/EntraIdAuthCode.property.test.ts +++ b/backend/test/properties/EntraIdAuthCode.property.test.ts @@ -110,7 +110,7 @@ describe('EntraIdService — Property 16: Authorization code single-use and TTL' const mockUserService = { findByFederatedIdentity: vi.fn().mockResolvedValue(null), - findByEmail: vi.fn().mockResolvedValue(null), + findAllByEmail: vi.fn().mockResolvedValue([]), createFederatedUser: vi.fn().mockResolvedValue(mockUser), getUserById: vi.fn().mockResolvedValue(mockUser), toUserDTO: vi.fn().mockReturnValue({ id: mockUser.id, username: mockUser.username }), diff --git a/backend/test/properties/EntraIdCallback.property.test.ts b/backend/test/properties/EntraIdCallback.property.test.ts index afe7fe8f..08b1a76b 100644 --- a/backend/test/properties/EntraIdCallback.property.test.ts +++ b/backend/test/properties/EntraIdCallback.property.test.ts @@ -221,7 +221,7 @@ describe('EntraIdService — Callback Validation Properties', () => { const mockUserService = { findByFederatedIdentity: vi.fn().mockResolvedValue(null), - findByEmail: vi.fn().mockResolvedValue(null), + findAllByEmail: vi.fn().mockResolvedValue([]), createFederatedUser: vi.fn().mockResolvedValue(mockUser), getUserById: vi.fn().mockResolvedValue(mockUser), toUserDTO: vi.fn().mockReturnValue({ id: mockUser.id, username: mockUser.username }), @@ -295,6 +295,8 @@ describe('EntraIdService — Callback Validation Properties', () => { const expiredAt = new Date(now.getTime() - minutesAgo * 60 * 1000); (db.queryOne as ReturnType).mockResolvedValue({ + id: 'identity', + userId: mockUser.id, state, nonce: 'test-nonce', code_verifier: 'test-verifier-value-that-is-long-enough', @@ -337,6 +339,8 @@ describe('EntraIdService — Callback Validation Properties', () => { function setupValidStateEntry(): void { const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); (db.queryOne as ReturnType).mockResolvedValue({ + id: 'identity', + userId: mockUser.id, state: 'valid-state', nonce: storedNonce, code_verifier: 'valid-code-verifier-value-here-long', @@ -420,6 +424,8 @@ describe('EntraIdService — Callback Validation Properties', () => { async ([storedNonce, tokenNonce], code) => { const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); (db.queryOne as ReturnType).mockResolvedValue({ + id: 'identity', + userId: mockUser.id, state: 'valid-state', nonce: storedNonce, code_verifier: 'valid-code-verifier-value-here-long', @@ -460,6 +466,8 @@ describe('EntraIdService — Callback Validation Properties', () => { function setupValidState(): void { const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); (db.queryOne as ReturnType).mockResolvedValue({ + id: 'identity', + userId: mockUser.id, state: 'valid-state', nonce: storedNonce, code_verifier: 'valid-code-verifier-value-here-long', @@ -556,6 +564,8 @@ describe('EntraIdService — Callback Validation Properties', () => { async (state, code) => { const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); (db.queryOne as ReturnType).mockResolvedValue({ + id: 'identity', + userId: mockUser.id, state, nonce: storedNonce, code_verifier: 'valid-code-verifier-value-here-long', @@ -604,6 +614,8 @@ describe('EntraIdService — Callback Validation Properties', () => { async (state, code) => { const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); (db.queryOne as ReturnType).mockResolvedValue({ + id: 'identity', + userId: mockUser.id, state, nonce: storedNonce, code_verifier: 'valid-code-verifier-value-here-long', diff --git a/backend/test/properties/EntraIdGroupSync.property.test.ts b/backend/test/properties/EntraIdGroupSync.property.test.ts index 21e25f10..3bf6c59c 100644 --- a/backend/test/properties/EntraIdGroupSync.property.test.ts +++ b/backend/test/properties/EntraIdGroupSync.property.test.ts @@ -21,6 +21,7 @@ describe('Entra group reconciliation against storage', () => { await initializeTestSchema(db); await db.execute(`INSERT INTO users (id, username, email, first_name, last_name, is_active, is_admin, created_at, updated_at) VALUES ('user', 'user', 'user@example.test', '', '', 1, 0, 'now', 'now')`); + await db.execute("INSERT INTO federated_identities (id, user_id, provider, subject, issuer, created_at, updated_at) VALUES ('identity', 'user', 'entra-id', 'subject', 'https://login.microsoftonline.com/tenant/v2.0', 'now', 'now')"); config = { enabled: true, tenantId: 'tenant', clientId: 'client', clientSecret: 'fixture', redirectUri: 'http://localhost/callback', scopes: ['openid'], jwksCacheTtlMs: 1000, groupMapping: { A: 'Viewer', B: 'Operator' } }; @@ -29,12 +30,12 @@ describe('Entra group reconciliation against storage', () => { }); afterEach(async () => { await db.close(); }); const grants = async (db: SQLiteAdapter, table: string) => - (await db.query<{ role_id: string }>(`SELECT role_id FROM ${table} WHERE user_id = 'user' ORDER BY role_id`)).map(row => row.role_id); + (await db.query<{ role_id: string }>(`SELECT DISTINCT role_id FROM ${table} WHERE user_id = 'user' ORDER BY role_id`)).map(row => row.role_id); it('reconciles arbitrary claim changes while preserving manual grants to the same role', async () => { await db.execute("INSERT INTO user_roles VALUES ('user', 'role-viewer-001', 'now')"); await fc.assert(fc.asyncProperty(fc.array(fc.boolean(), { minLength: 2, maxLength: 2 }), async ([viewer, operator]) => { - await service.syncGroupRoles('user', [...(viewer ? ['a'] : []), ...(operator ? ['b'] : [])]); + await service.syncGroupRoles('identity', [...(viewer ? ['a'] : []), ...(operator ? ['b'] : [])]); expect(await grants(db, 'federated_user_roles')).toEqual([ ...(operator ? ['role-operator-001'] : []), ...(viewer ? ['role-viewer-001'] : []), ]); @@ -44,36 +45,39 @@ describe('Entra group reconciliation against storage', () => { it('removes provider grants when groups or the mapping disappear and invalidates cached permissions', async () => { const permissions = new PermissionService(db); - await service.syncGroupRoles('user', ['A']); + await service.syncGroupRoles('identity', ['A']); expect(await permissions.hasPermission('user', 'executions', 'read')).toBe(true); - await service.syncGroupRoles('user', undefined); + await service.syncGroupRoles('identity', undefined); expect(await permissions.hasPermission('user', 'executions', 'read')).toBe(false); - await service.syncGroupRoles('user', ['A']); + await service.syncGroupRoles('identity', ['A']); config.groupMapping = null; - await service.syncGroupRoles('user', ['A']); + await service.syncGroupRoles('identity', ['A']); expect(await grants(db, 'federated_user_roles')).toEqual([]); }); it('reconciles legacy grants once, without erasing subsequent manual assignments', async () => { await db.execute("INSERT INTO user_roles VALUES ('user', 'role-viewer-001', 'now')"); await db.execute("INSERT INTO legacy_federated_user_roles VALUES ('user', 'role-viewer-001')"); - await service.syncGroupRoles('user', []); + await service.syncGroupRoles('identity', []); expect(await grants(db, 'user_roles')).toEqual([]); await db.execute("INSERT INTO user_roles VALUES ('user', 'role-viewer-001', 'now')"); - await service.syncGroupRoles('user', []); + await service.syncGroupRoles('identity', []); expect(await grants(db, 'user_roles')).toEqual(['role-viewer-001']); }); it('rolls back partial reconciliation and fails login work when a mapped role is invalid', async () => { - await service.syncGroupRoles('user', ['B']); + await service.syncGroupRoles('identity', ['B']); config.groupMapping = { A: 'Viewer', B: 'Missing role' }; - await expect(service.syncGroupRoles('user', ['A', 'B'])).rejects.toThrow('unknown role'); + await expect(service.syncGroupRoles('identity', ['A', 'B'])).rejects.toThrow('unknown role'); expect(await grants(db, 'federated_user_roles')).toEqual(['role-operator-001']); }); - it('supports duplicate targets and simultaneous reconciliation without duplicate grants', async () => { + it('retains both group sources under simultaneous reconciliation to the same role', async () => { config.groupMapping = { A: 'Viewer', B: 'viewer' }; - await Promise.all(Array.from({ length: 8 }, () => service.syncGroupRoles('user', ['A', 'B']))); + await Promise.all(Array.from({ length: 8 }, () => service.syncGroupRoles('identity', ['A', 'B']))); expect(await grants(db, 'federated_user_roles')).toEqual(['role-viewer-001']); + expect(await db.query('SELECT source_key FROM federated_user_roles ORDER BY source_key')).toEqual([ + { source_key: 'group:a' }, { source_key: 'group:b' }, + ]); }); }); diff --git a/backend/test/properties/EntraIdProvisioning.property.test.ts b/backend/test/properties/EntraIdProvisioning.property.test.ts index 496b3a1f..8d452b68 100644 --- a/backend/test/properties/EntraIdProvisioning.property.test.ts +++ b/backend/test/properties/EntraIdProvisioning.property.test.ts @@ -74,6 +74,8 @@ function createMockUser(overrides: Partial = {}): User { username: 'testuser', email: 'user@example.com', passwordHash: '', + localAuthEnabled: 0, + displayName: null, firstName: 'Test', lastName: 'User', isActive: 1, @@ -144,7 +146,7 @@ describe('EntraIdService — User Provisioning Properties', () => { mockUserService = { findByFederatedIdentity: vi.fn().mockResolvedValue(null), - findByEmail: vi.fn().mockResolvedValue(null), + findAllByEmail: vi.fn().mockResolvedValue([]), createFederatedUser: vi.fn().mockImplementation(async (claims: IdTokenClaims) => { return createMockUser({ id: `new-user-${claims.sub}`, @@ -207,7 +209,7 @@ describe('EntraIdService — User Provisioning Properties', () => { async (claims) => { // Reset mocks for each iteration vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); - vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + vi.mocked(mockUserService.findAllByEmail).mockResolvedValue([]); vi.mocked(mockUserService.createFederatedUser).mockResolvedValue( createMockUser({ id: `new-user-${claims.sub}`, @@ -250,7 +252,7 @@ describe('EntraIdService — User Provisioning Properties', () => { validClaimsArb, async (claims) => { vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); - vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + vi.mocked(mockUserService.findAllByEmail).mockResolvedValue([]); const createdUser = createMockUser({ id: `new-user-${claims.sub}`, @@ -384,7 +386,7 @@ describe('EntraIdService — User Provisioning Properties', () => { }; vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); - vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + vi.mocked(mockUserService.findAllByEmail).mockResolvedValue([]); // Capture what createFederatedUser receives to verify username derivation let receivedClaims: IdTokenClaims | null = null; @@ -447,7 +449,7 @@ describe('EntraIdService — User Provisioning Properties', () => { }; vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); - vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + vi.mocked(mockUserService.findAllByEmail).mockResolvedValue([]); vi.mocked(mockUserService.createFederatedUser).mockImplementation( async (c: IdTokenClaims) => { const username = c.email.split('@')[0] @@ -491,7 +493,7 @@ describe('EntraIdService — User Provisioning Properties', () => { }; vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); - vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + vi.mocked(mockUserService.findAllByEmail).mockResolvedValue([]); vi.mocked(mockUserService.createFederatedUser).mockImplementation( async (c: IdTokenClaims) => { const username = c.email.split('@')[0] diff --git a/backend/test/properties/user/email-uniqueness.property.test.ts b/backend/test/properties/user/email-uniqueness.property.test.ts index bff61d6a..4b8e787a 100644 --- a/backend/test/properties/user/email-uniqueness.property.test.ts +++ b/backend/test/properties/user/email-uniqueness.property.test.ts @@ -201,7 +201,7 @@ describe('Email Uniqueness Properties', () => { // Verify all users can still be retrieved by email for (const user of createdUsers) { - const retrieved = await userService.getUserByEmail(user.email); + const retrieved = await userService.findLocalByEmail(user.email!); expect(retrieved).not.toBeNull(); expect(retrieved?.id).toBe(user.id); expect(retrieved?.email).toBe(user.email); diff --git a/backend/test/services/AuthenticationService.bruteforce.test.ts b/backend/test/services/AuthenticationService.bruteforce.test.ts index 8a7bf553..a850c669 100644 --- a/backend/test/services/AuthenticationService.bruteforce.test.ts +++ b/backend/test/services/AuthenticationService.bruteforce.test.ts @@ -3,6 +3,7 @@ import { SQLiteAdapter } from '../../src/database/SQLiteAdapter'; import type { DatabaseAdapter } from '../../src/database/DatabaseAdapter'; import { AuthenticationService } from '../../src/services/AuthenticationService'; import { randomUUID } from 'crypto'; +import { initializeTestSchema } from '../helpers/schema'; describe('AuthenticationService - Brute Force Protection', () => { let db: DatabaseAdapter; @@ -16,117 +17,7 @@ describe('AuthenticationService - Brute Force Protection', () => { db = new SQLiteAdapter(':memory:'); await db.initialize(); - // Initialize schema - await runQuery(db, ` - CREATE TABLE users ( - id TEXT PRIMARY KEY, - username TEXT NOT NULL UNIQUE, - email TEXT NOT NULL UNIQUE, - password_hash TEXT NOT NULL, - session_version TEXT NOT NULL DEFAULT '0', - first_name TEXT NOT NULL, - last_name TEXT NOT NULL, - is_active INTEGER NOT NULL DEFAULT 1, - is_admin INTEGER NOT NULL DEFAULT 0, - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL, - last_login_at TEXT - ) - `); - - await runQuery(db, ` - CREATE TABLE roles ( - id TEXT PRIMARY KEY, - name TEXT NOT NULL UNIQUE, - description TEXT NOT NULL, - is_built_in INTEGER NOT NULL DEFAULT 0, - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL - ) - `); - - await runQuery(db, ` - CREATE TABLE user_roles ( - user_id TEXT NOT NULL, - role_id TEXT NOT NULL, - assigned_at TEXT NOT NULL, - PRIMARY KEY (user_id, role_id) - ) - `); - - await runQuery(db, ` - CREATE TABLE group_roles ( - group_id TEXT NOT NULL, - role_id TEXT NOT NULL, - assigned_at TEXT NOT NULL, - PRIMARY KEY (group_id, role_id) - ) - `); - - await runQuery(db, ` - CREATE TABLE user_groups ( - user_id TEXT NOT NULL, - group_id TEXT NOT NULL, - assigned_at TEXT NOT NULL, - PRIMARY KEY (user_id, group_id) - ) - `); - - await runQuery(db, ` - CREATE TABLE revoked_tokens ( - token TEXT PRIMARY KEY, - user_id TEXT NOT NULL, - revoked_at TEXT NOT NULL, - expires_at TEXT NOT NULL - ) - `); - - // Create brute force protection tables - await runQuery(db, ` - CREATE TABLE failed_login_attempts ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - username TEXT NOT NULL, - attempted_at TEXT NOT NULL, - ip_address TEXT, - reason TEXT - ) - `); - - await runQuery(db, ` - CREATE TABLE account_lockouts ( - username TEXT PRIMARY KEY, - lockout_type TEXT NOT NULL, - locked_at TEXT NOT NULL, - locked_until TEXT, - failed_attempts INTEGER NOT NULL DEFAULT 0, - last_attempt_at TEXT - ) - `); - - await runQuery(db, ` - CREATE TABLE login_attempt_counters ( - username TEXT PRIMARY KEY, - cumulative_failed_attempts INTEGER NOT NULL DEFAULT 0, - last_failed_at TEXT - ) - `); - - await runQuery(db, ` - CREATE TABLE config ( - key TEXT PRIMARY KEY, - value TEXT NOT NULL, - updated_at TEXT NOT NULL - ) - `); - - await runQuery(db, ` - INSERT INTO config (key, value, updated_at) VALUES - ('allow_self_registration', 'false', datetime('now')), - ('default_new_user_role', 'role-viewer-001', datetime('now')) - `); - - // Create test user - await db.execute('CREATE VIEW effective_user_roles AS SELECT user_id, role_id FROM user_roles'); + await initializeTestSchema(db); authService = new AuthenticationService(db, 'test-secret-key-for-route-tests-32chars'); const passwordHash = await authService.hashPassword(testPassword); diff --git a/backend/test/unit/services/EntraIdService.test.ts b/backend/test/unit/services/EntraIdService.test.ts index 5c061090..3f29a10b 100644 --- a/backend/test/unit/services/EntraIdService.test.ts +++ b/backend/test/unit/services/EntraIdService.test.ts @@ -220,7 +220,7 @@ describe('EntraIdService', () => { describe('provisionUser()', () => { let mockUserService: { findByFederatedIdentity: ReturnType; - findByEmail: ReturnType; + findAllByEmail: ReturnType; createFederatedUser: ReturnType; linkFederatedIdentity: ReturnType; }; @@ -231,6 +231,8 @@ describe('EntraIdService', () => { username: 'testuser', email: 'test@example.com', passwordHash: 'hashed', + localAuthEnabled: 1, + displayName: null, firstName: 'Test', lastName: 'User', isActive: 1, @@ -255,7 +257,7 @@ describe('EntraIdService', () => { beforeEach(() => { mockUserService = { findByFederatedIdentity: vi.fn().mockResolvedValue(null), - findByEmail: vi.fn().mockResolvedValue(null), + findAllByEmail: vi.fn().mockResolvedValue([]), createFederatedUser: vi.fn().mockResolvedValue(baseUser), linkFederatedIdentity: vi.fn().mockResolvedValue({ id: 'fed-id-1', @@ -308,11 +310,11 @@ describe('EntraIdService', () => { // Must not call create or link expect(mockUserService.createFederatedUser).not.toHaveBeenCalled(); expect(mockUserService.linkFederatedIdentity).not.toHaveBeenCalled(); - expect(mockUserService.findByEmail).not.toHaveBeenCalled(); + expect(mockUserService.findAllByEmail).not.toHaveBeenCalled(); }); it('rejects an email collision without linking or creating an account', async () => { - mockUserService.findByEmail.mockResolvedValue(baseUser); + mockUserService.findAllByEmail.mockResolvedValue([baseUser]); await expect(provisionService.provisionUser(baseClaims)).rejects.toMatchObject({ code: 'IDENTITY_COLLISION' }); expect(mockUserService.linkFederatedIdentity).not.toHaveBeenCalled(); expect(mockUserService.createFederatedUser).not.toHaveBeenCalled(); @@ -320,7 +322,7 @@ describe('EntraIdService', () => { it('creates new federated user when no match found', async () => { mockUserService.findByFederatedIdentity.mockResolvedValue(null); - mockUserService.findByEmail.mockResolvedValue(null); + mockUserService.findAllByEmail.mockResolvedValue([]); const newUser = { ...baseUser, id: 'new-user-456' }; mockUserService.createFederatedUser.mockResolvedValue(newUser); @@ -333,7 +335,7 @@ describe('EntraIdService', () => { it('wraps createFederatedUser errors as PROVISIONING_FAILED', async () => { mockUserService.findByFederatedIdentity.mockResolvedValue(null); - mockUserService.findByEmail.mockResolvedValue(null); + mockUserService.findAllByEmail.mockResolvedValue([]); mockUserService.createFederatedUser.mockRejectedValue( new Error('UNIQUE constraint failed: users.username'), ); @@ -346,11 +348,11 @@ describe('EntraIdService', () => { it('proceeds to createFederatedUser when email is present but no email match', async () => { mockUserService.findByFederatedIdentity.mockResolvedValue(null); - mockUserService.findByEmail.mockResolvedValue(null); + mockUserService.findAllByEmail.mockResolvedValue([]); await provisionService.provisionUser(baseClaims); - expect(mockUserService.findByEmail).toHaveBeenCalledWith(baseClaims.email); + expect(mockUserService.findAllByEmail).toHaveBeenCalledWith(baseClaims.email); expect(mockUserService.createFederatedUser).toHaveBeenCalledWith(baseClaims); }); @@ -365,14 +367,14 @@ describe('EntraIdService', () => { await provisionService.provisionUser(claims); - // findByEmail should not be called with empty string - expect(mockUserService.findByEmail).not.toHaveBeenCalled(); + // findAllByEmail should not be called with empty string + expect(mockUserService.findAllByEmail).not.toHaveBeenCalled(); expect(mockUserService.createFederatedUser).toHaveBeenCalledWith(claims); }); it('logs provisioning actions without exposing tokens or secrets', async () => { mockUserService.findByFederatedIdentity.mockResolvedValue(null); - mockUserService.findByEmail.mockResolvedValue(null); + mockUserService.findAllByEmail.mockResolvedValue([]); await provisionService.provisionUser(baseClaims); diff --git a/docs/api.md b/docs/api.md index 2736f0e9..9d41570f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -768,6 +768,14 @@ All endpoints require access JWT authentication and appropriate RBAC permissions ### Users +User DTOs from authentication and user administration include nullable `email` +and `displayName` fields. Group member DTOs also allow a null `email`. External +contact email can be absent or shared across accounts; it never identifies an +account for linking. Local account creation still requires a unique local email +and username. The `ldap:` username prefix is reserved for directory accounts. +Password hashes are excluded from responses. Entra enrollment continues to +require explicit administrative authority and rejects implicit email linking. + | Method | Endpoint | Description | |---|---|---| | `POST` | `/api/users` | Create user | diff --git a/docs/internal/plans/ldap-authentication.md b/docs/internal/plans/ldap-authentication.md new file mode 100644 index 00000000..ab7b6b4f --- /dev/null +++ b/docs/internal/plans/ldap-authentication.md @@ -0,0 +1,602 @@ +# LDAP authentication implementation plan + +**Status:** Package 1 complete; packages 2 through 7 pending +**Date:** 2026-10-21 +**Scope:** OpenLDAP and Active Directory authentication, directory group authorization, and provider-bound session revalidation + +## Agreed behavior + +Pabawi will authenticate users against one configured LDAP directory, with optional equivalent endpoints for failover. Local authentication, Entra ID, and LDAP can operate simultaneously. Users explicitly select a password authentication provider; a failed attempt never falls through to another provider. + +Connection credentials, TLS, search settings, and directory policy come from environment variables. Administrators search selected directory groups and map them directly to Pabawi roles through access administration. These mappings live in the database. There is no full-directory user import or synchronization job. + +An LDAP user gets a Pabawi account after successful credential and eligibility verification. Access requires at least one explicitly granted role, either through directory groups or a manual Pabawi assignment. New LDAP accounts receive no automatic default role. Accounts without grants can remain visible to administrators for subsequent manual assignment, but receive no session tokens. + +Directory identities remain separate from local and Entra identities, even when login names or email addresses match. LDAP passwords are used only for the current bind and are never persisted or retained for later revalidation. Directory writes, password changes, account linking, bulk synchronization, FreeIPA-specific behavior, RFC2307 `posixGroup` membership, and LDAP-specific MFA are outside this implementation. + +## Current architecture and required changes + +These observations describe the code inspected for this plan. Proposed interfaces and configuration below are implementation contracts, not existing functionality. + +| Existing surface | Current behavior | Required change | +| --- | --- | --- | +| `backend/src/routes/auth.ts` | Provider discovery advertises local and optional Entra; password login is local | Advertise LDAP public metadata and add an explicit LDAP login route | +| `backend/src/server.ts` | Entra is an authentication service outside the infrastructure plugin registry | Wire LDAP authentication and shared eligibility dependencies alongside authentication services | +| `backend/src/config/ConfigService.ts` | Parses and validates environment configuration | Add typed LDAP configuration and conditional validation; do not read `process.env` in LDAP services | +| `backend/src/services/UserService.ts` | Federated creation accepts Entra claims and hardcodes its provider | Extract provider-neutral transactional account provisioning while preserving Entra behavior | +| `backend/src/services/AuthenticationService.ts` | Shared token issuance and rotation; tokens lack provider context | Bind tokens to the authenticating identity and enforce LDAP eligibility on verification and refresh | +| `backend/src/middleware/authMiddleware.ts` | Creates its own authentication service and exposes `req.revalidateAuth` | Use shared configured authentication dependencies so request and stream checks see LDAP state | +| `backend/src/services/SessionAuthorization.ts` | Periodically checks authorization for long-lived connections | Keep its checks and place bounded LDAP freshness underneath them | +| `backend/src/services/PermissionService.ts` | Uses effective roles and database authorization revisions | Include LDAP grants and invalidate permissions on their mutation | +| `backend/src/database/migrations/016_entra_id_auth.sql`, `022_repair_entra_id_auth.sql` | Identity uniqueness is `(provider, subject)` although lookup also includes issuer | Include stable directory/provider scope in identity uniqueness and lookup | +| `backend/src/database/migrations/027_sso_boundaries.sqlite.sql` and PostgreSQL counterpart | Federated role grants lack identity provenance | Separate grants by source identity so one provider cannot erase another provider's grants | +| `frontend/src/pages/LoginPage.svelte` | Password form applies local minimum username/password lengths | For LDAP, require nonempty input and reasonable payload limits; do not impose local password creation rules | +| `frontend/src/lib/entraIdAuth.svelte.ts` | Provider discovery is Entra-specific | Extract common discovery while retaining Entra redirect handling | + +Authentication does not belong in `plugins/registry.ts`: that registry manages infrastructure integrations. Add focused authentication services rather than introducing an unrelated plugin framework. + +## Environment configuration + +### Parsing and defaults + +Use the existing configuration type definitions and `ConfigService` validation. `LDAP_ENABLED=false` is the default. When enabled, malformed configuration fails startup. Valid configuration with an unreachable directory permits startup with LDAP unavailable and local access intact. Configuration changes require restart. + +The primary host/port and additional endpoints must describe the same logical directory: identical identity attributes, search bases, schema, and policy. The stable directory ID must survive hostname changes. Pointing it at a different directory requires an intentional identity migration, not an ordinary endpoint edit. + +| Variable | Default and contract | Secret | +| --- | --- | --- | +| `LDAP_ENABLED` | `false`; strict boolean | no | +| `LDAP_DIRECTORY_ID` | Required when enabled; stable operator-chosen identifier, restricted to letters, digits, `_`, and `-` | no | +| `LDAP_DIRECTORY_TYPE` | Required: `ad` or `openldap` | no | +| `LDAP_DISPLAY_NAME` | `LDAP`; provider label in login and user administration | no | +| `LDAP_LOGIN_HELP_URL` | Empty; optional HTTP(S) help link, safely rendered | no | +| `LDAP_HOSTNAME` | Required FQDN; no embedded credentials, protocol, path, or search parameters | no | +| `LDAP_PORT` | `636` for LDAPS, `389` for StartTLS; integer 1 through 65535 | no | +| `LDAP_FAILOVER_ENDPOINTS` | `[]`; JSON array of additional `{ "hostname": "...", "port": 636 }` objects; maximum four | no | +| `LDAP_TLS_MODE` | `ldaps`; either `ldaps` or `starttls`; applies to every endpoint | no | +| `LDAP_CA_FILE` | Empty uses system trust; otherwise readable PEM CA bundle path, added to system trust | no | +| `LDAP_ALLOW_WILDCARD_CERTIFICATES` | `false`; additional restriction beyond normal hostname validation | no | +| `LDAP_LOOKUP_USER` | Required DN unless anonymous lookup is explicitly enabled | no | +| `LDAP_LOOKUP_PASSWORD` | Required nonempty value with lookup user; never expose in discovery, logs, or diagnostics | yes | +| `LDAP_ANONYMOUS_LOOKUP` | `false`; when true, lookup user/password must both be absent | no | +| `LDAP_CONNECT_TIMEOUT_SECONDS` | `10`; positive integer, at most 30 | no | +| `LDAP_OPERATION_TIMEOUT_SECONDS` | `10`; positive integer, at most 30 | no | +| `LDAP_REQUEST_TIMEOUT_SECONDS` | `30`; total LDAP transaction deadline across endpoints, binds, searches, and traversal; at most 60 | no | +| `LDAP_BASE_DN` | Required nonempty valid DN | no | +| `LDAP_USER_RDN` | Empty; optional relative DN beneath base DN | no | +| `LDAP_USER_OBJECT_CLASS` | `user` for AD, `inetOrgPerson` for OpenLDAP | no | +| `LDAP_USER_LOOKUP_ATTR` | `sAMAccountName` for AD, `uid` for OpenLDAP | no | +| `LDAP_USER_ID_ATTR` | `objectGUID` for AD, `entryUUID` for OpenLDAP; must be immutable and readable | no | +| `LDAP_USER_EMAIL_ATTR` | `mail`; missing value becomes null, never a fabricated address | no | +| `LDAP_USER_DISPLAY_NAME_ATTR` | `displayName`; fallback to current directory login name | no | +| `LDAP_USER_GIVEN_NAME_ATTR` | `givenName`; missing value becomes an empty profile field | no | +| `LDAP_USER_SURNAME_ATTR` | `sn`; missing value becomes an empty profile field | no | +| `LDAP_USER_ELIGIBILITY_FILTER` | Empty for AD means built-in AD policy; required valid filter for OpenLDAP | no | +| `LDAP_GROUP_RDN` | Empty; optional relative DN beneath base DN | no | +| `LDAP_GROUP_OBJECT_CLASS` | `group` for AD, `groupOfUniqueNames` for OpenLDAP | no | +| `LDAP_GROUP_MEMBER_ATTR` | `member` for AD, `uniqueMember` for OpenLDAP; DN-valued memberships only | no | +| `LDAP_GROUP_ID_ATTR` | `objectGUID` for AD, `entryUUID` for OpenLDAP | no | +| `LDAP_GROUP_NAME_ATTR` | `name` for AD, `displayName` for OpenLDAP; display falls back to lookup attribute | no | +| `LDAP_GROUP_LOOKUP_ATTR` | `cn`; used for administrative search, not persistent identity | no | +| `LDAP_SEARCH_NESTED_GROUPS` | `false`; direct membership only unless enabled | no | +| `LDAP_DISABLE_MATCHING_RULE_IN_CHAIN` | `false`; AD optimization switch, irrelevant for OpenLDAP | no | +| `LDAP_NESTED_GROUP_MAX_DEPTH` | `10`; positive integer, at most 32 | no | +| `LDAP_GROUP_SEARCH_LIMIT` | `100`; total returned administrative search entries, at most 500 | no | +| `LDAP_GROUP_TRAVERSAL_LIMIT` | `1000`; maximum visited groups per eligibility transaction, at most 10000 | no | +| `LDAP_REVALIDATION_INTERVAL_SECONDS` | `300`; positive integer at most 300, so operators can tighten the agreed freshness bound | no | +| `LDAP_MAX_CONCURRENT_OPERATIONS` | `10`; positive integer at most 100; bounded admission, with excess requests rejected temporarily | no | + +Validate attribute descriptions as LDAP attribute names/OIDs, DNs with a DN parser, and filters with a filter parser. Do not treat an arbitrary configured attribute name as safe filter syntax. Combine fixed administrative filters with escaped runtime values; do not support executable templates or raw client-supplied filters. + +TLS certificate verification and hostname checking are mandatory, with TLS 1.2 or newer. There is no environment option to disable them. Wildcard permission, when enabled, still uses standard hostname matching. With the default restriction, reject wildcard identities used to match the endpoint. Apply identical checks to LDAPS and StartTLS, including SNI for each selected FQDN. A failed StartTLS negotiation never falls back to plaintext. + +### Active Directory example + +Proposed additions to `backend/.env.example`; these variables are not implemented yet: + +```dotenv +LDAP_ENABLED=true +LDAP_DIRECTORY_ID=corporate-ad +LDAP_DIRECTORY_TYPE=ad +LDAP_DISPLAY_NAME=Corporate directory +LDAP_HOSTNAME=dc1.example.com +LDAP_PORT=636 +LDAP_FAILOVER_ENDPOINTS='[{"hostname":"dc2.example.com","port":636}]' +LDAP_TLS_MODE=ldaps +LDAP_CA_FILE=/etc/pabawi/corporate-ca.pem +LDAP_LOOKUP_USER=CN=pabawi-reader,OU=Service Accounts,DC=example,DC=com +# Set LDAP_LOOKUP_PASSWORD in the protected runtime environment. +LDAP_BASE_DN=DC=example,DC=com +LDAP_USER_RDN=OU=People +LDAP_GROUP_RDN=OU=Groups +LDAP_SEARCH_NESTED_GROUPS=false +LDAP_REVALIDATION_INTERVAL_SECONDS=300 +``` + +The unset lookup password intentionally prevents this example from starting until a real secret is supplied. Use a read-only account with visibility of the relevant user status and membership attributes. The configured user search base must uniquely resolve a login name; `sAMAccountName` is not assumed unique across multiple domains. Forest-wide discovery and cross-domain referrals are excluded. + +### OpenLDAP example + +```dotenv +LDAP_ENABLED=true +LDAP_DIRECTORY_ID=corporate-openldap +LDAP_DIRECTORY_TYPE=openldap +LDAP_DISPLAY_NAME=Corporate directory +LDAP_HOSTNAME=ldap1.example.com +LDAP_PORT=389 +LDAP_TLS_MODE=starttls +LDAP_CA_FILE=/etc/pabawi/corporate-ca.pem +LDAP_LOOKUP_USER=cn=pabawi-reader,ou=services,dc=example,dc=com +# Set LDAP_LOOKUP_PASSWORD in the protected runtime environment. +LDAP_BASE_DN=dc=example,dc=com +LDAP_USER_RDN=ou=people +LDAP_USER_LOOKUP_ATTR=uid +LDAP_USER_ID_ATTR=entryUUID +# Example policy only: employeeType must exist in this deployment's schema. +LDAP_USER_ELIGIBILITY_FILTER=(employeeType=active) +LDAP_GROUP_RDN=ou=groups +LDAP_GROUP_OBJECT_CLASS=groupOfUniqueNames +LDAP_GROUP_MEMBER_ATTR=uniqueMember +LDAP_GROUP_ID_ATTR=entryUUID +LDAP_SEARCH_NESTED_GROUPS=false +``` + +OpenLDAP presets select schema attributes, not a universal account status policy. Operators must supply a positive eligibility filter and document which disabled, locked, and expired states it excludes. Test that missing status attributes do not inadvertently make a user eligible. A deployment using `groupOfNames` can override the class and membership attribute to `groupOfNames` and `member`. Memberships expressed as usernames, such as `memberUid`, require separate future support. Initially support the ordinary DN form of `uniqueMember`; reject unsupported optional UID suffixes rather than interpreting them incorrectly. + +### Relationship to Puppet Enterprise settings + +This is conceptual compatibility, not a promise to accept PE RBAC API payloads. The source of the terminology is [PE external directory settings](https://help.puppet.com/pe/current/topics/rbac_ldap_ext_directory_settings.htm). That retrieved page identifies itself as 2025.8; the requested [2025.12.0 URL](https://help.puppet.com/pe/2025.12.0/topics/rbac_ldap_ext_directory_settings.htm) was unavailable during design. + +| PE concept | Pabawi equivalent | +| --- | --- | +| Directory name and login help | `LDAP_DISPLAY_NAME`, `LDAP_LOGIN_HELP_URL` | +| Hostname, port, lookup user/password, timeout | Corresponding `LDAP_*` connection variables | +| SSL and StartTLS booleans | Single `LDAP_TLS_MODE` choice | +| Certificate chain | `LDAP_CA_FILE` | +| Hostname and wildcard validation | Mandatory hostname validation; optional wildcard permission | +| Base DN and user/group relative DNs | `LDAP_BASE_DN`, `LDAP_USER_RDN`, `LDAP_GROUP_RDN` | +| User login, email, full name attributes | Corresponding lookup/email/display name variables | +| Group object class, member, display, and lookup attributes | Corresponding `LDAP_GROUP_*` variables | +| Nested groups and matching rule switch | `LDAP_SEARCH_NESTED_GROUPS`, `LDAP_DISABLE_MATCHING_RULE_IN_CHAIN` | + +Pabawi additionally needs immutable user/group IDs, explicit eligibility policy, endpoint failover, query limits, and session freshness settings. Unlike the optional security choices in the reference, this design requires TLS and hostname validation. + +## Identity and database design + +### Accounts and profile ownership + +Keep the existing globally unique `users.username` as an internal identifier. New LDAP accounts receive a deterministic reserved identifier derived from provider, directory ID, and immutable subject, not their mutable login name. Encode components unambiguously and reserve this namespace from local account creation. Store directory login name and display name separately. Preserve existing local usernames and existing Entra accounts; do not mass-rename them. + +Make contact email nullable and nonunique for external accounts. Preserve local email requirements and uniqueness through an explicit local credential/account scope and a corresponding database constraint. Never use a global `findByEmail(): User | null` contract once duplicate emails are legal. Replace ambiguous callers with scoped local lookup or an explicit set of matches. Preserve the existing Entra collision rejection policy with an explicit query; changing the email index must not silently enable linking or change Entra enrollment behavior. + +Use nullable password hash types consistently in backend and frontend DTOs. A directory-only user has no local password. Authenticated password changes and administrative password updates must reject LDAP accounts. Existing explicitly enrolled Entra accounts that already have local credentials keep their established behavior. + +Add a dedicated display name field rather than splitting arbitrary full names into invented first and last names. Refresh LDAP login, display name, given name, surname, and contact email from directory data at login and successful revalidation. Profile refresh never alters Pabawi suspension, manual grants, or administrative status. LDAP profile fields are read-only through user management APIs as well as the UI. + +There is currently no email password recovery workflow. Preserve unambiguous local credential operations now; any future email recovery must select a local account explicitly and cannot resolve an account from an unscoped email match. + +### Required logical records + +Choose new migration numbers from the repository's current sequence during implementation. Implement equivalent SQLite and PostgreSQL migrations through `DatabaseService`. + +| Record | Required fields and invariants | +| --- | --- | +| Federated identity | Existing ID and user reference, provider, stable issuer/directory scope, immutable subject; unique `(provider, issuer, subject)` | +| LDAP identity metadata | Identity reference, current login name, DN and profile metadata; DN/login are mutable locators, never identity keys | +| External group mapping | ID, directory ID, immutable group subject, current DN/name, role ID, enabled flag, audit timestamps; unique `(directory_id, group_subject, role_id)` | +| External role grant | User ID, role ID, identity/source ownership, mapping ID when group-derived; retain multiple provenance rows when several mappings grant one role | +| LDAP validation state | Identity ID, last successful validation timestamp, monotonically increasing validation generation, and applicable mapping/config revision | +| LDAP validation lease | Identity ID, lease owner/expiry and fencing generation for cross-process refresh coordination | + +Reuse and extend `federated_identities` and `federated_user_roles` where this produces a coherent model. Do not create a second unsynchronized identity store. Entra reconciliation must delete only Entra-owned grants; LDAP reconciliation must delete only LDAP-owned grants. Manual `user_roles` and local group assignments remain separate. Backfill existing Entra grants with ownership, including accounts explicitly enrolled from local authentication, without dropping permissions. + +Update `effective_user_roles`, permission queries, authorization revision triggers, and indexes on both database adapters. Deduplicate effective roles while preserving grant provenance. Removing one mapping cannot remove an identical role still granted by another mapping or manually. + +Provision user, identity, initial grants, and validation state atomically. Resolve concurrent first logins using database identity uniqueness and a transaction retry/read strategy; never create two users for the same immutable identity. For a proven identity with no grants, commit the account without tokens so an administrator can later grant a role. Failed binds must not provision accounts. + +SQLite table rebuilds must preserve dependent foreign keys, indexes, views, triggers, and data. Test upgrades from real migrated databases, not only freshly created schemas. Existing identity references must remain stable. + +## Authentication services and login flow + +Add `LdapDirectoryService` for read-only connection/search/bind operations and `LdapAuthenticationService` for provisioning and authorization orchestration. Add a shared provider-aware session eligibility service usable by every authentication entry point. Follow existing typed errors and structured `LoggerService` metadata. Do not introduce a separate token implementation. + +Use `ldapts` as the proposed TypeScript client, with its exact release pinned in the lockfile after checking Node engine compatibility and package review. Its documented client supports LDAPS, `startTLS()`, connection/operation timeouts, binary attributes, paginated searches, filter escaping, and `unbind()`. Use dedicated user-bind connections and close clients in `finally`. The API references are the [ldapts repository](https://github.com/ldapts/ldapts); filter construction must conform to [RFC 4515](https://www.rfc-editor.org/rfc/rfc4515). + +The login transaction is: + +1. Require explicit LDAP selection and nonempty username/password. Apply body limits and rate limits before directory work. Do not trim or normalize passwords. Use case-preserving login input and the directory's matching semantics. +2. Select an endpoint, establish verified TLS, and bind the lookup account, or explicitly bind anonymously. No credential-bearing operation precedes StartTLS. +3. Search under `USER_RDN + BASE_DN` using the configured user class, escaped login equality, and eligibility policy. Request only needed identity, profile, and status attributes. Require exactly one result and a valid immutable ID. Zero results, ambiguity, or incomplete/limited results cannot authenticate. +4. Open a separate TLS connection to the same endpoint and bind with the returned user DN and supplied password. Never construct a user DN from submitted text. Never rebind a shared lookup client as the user. +5. With the lookup connection, read current status and resolve mapped direct/nested groups. Check the same immutable identity after the user bind so a changed locator cannot attach credentials to another object. Treat directory changes during authentication as a retryable transaction failure, not an identity substitution. +6. Transactionally provision or update the account and LDAP-owned grants, respecting local suspension. Evaluate effective explicit roles, including manual assignments. Issue no tokens if the user has no role or remains suspended. +7. Generate the existing Pabawi token pair with authenticated provider/identity context. Audit the result with safe reason codes and clear transient credential references on exit. + +Reject empty passwords before calling LDAP: a server accepting an unauthenticated bind must never authenticate an empty password. Automatic reconnect/rebind must not replay user credentials or resume a StartTLS session without reestablishing TLS. Use transaction-scoped clients; discard a connection when its TLS or bind state is uncertain. + +Canonicalize `entryUUID` as a validated UUID. Read AD `objectGUID` as binary, with a single tested canonical encoding for persistence and filter reconstruction. Do not use lossy text decoding, DN lowercasing, or a mutable login as the subject. Missing identity attributes are configuration/data failures, not permission to fall back to the DN. + +### Eligibility policy + +For AD, evaluate supported account disablement, account expiration, lockout, and password-expiration indicators using documented attributes and server-computed state where readable. Distinguish Windows FILETIME values from Unix timestamps and test sentinel values. Make the required readable attributes part of diagnostics. A configured extra eligibility filter further restricts the built-in policy and cannot bypass it. + +For OpenLDAP, use the operator's configured filter on every eligibility search. If policy relies on operational attributes, request them explicitly. Diagnostics must distinguish a readable inactive account from missing policy visibility where possible. A successful bind is necessary at login, but not a substitute for a revalidation policy. + +Password changes or conditions observable only during a user bind cannot reliably be detected later without the password. Do not claim otherwise. Revalidation enforces directory existence and the status/membership information available to the lookup identity; fresh authentication is required for bind-only conditions. + +## Group resolution and role administration + +Map external groups directly to roles, following the existing federated-role approach. Do not mirror every external group into local Pabawi RBAC groups. Add controls alongside `RoleManagementPage.svelte` and `RoleDetailDialog.svelte`, with provider/source information in user administration. `GroupDetailPage.svelte` manages infrastructure node groups and is not the appropriate surface. + +Administrator group search uses `GROUP_RDN + BASE_DN`, the configured object class, and an escaped name/lookup substring with server-enforced limits. Return current display/lookup name, DN, and immutable ID. Creating a mapping resolves the submitted immutable ID against the configured directory and confirms the target role. A DN or display label supplied by the browser is not authoritative. + +For direct membership, test whether each mapped group contains the user's current DN in the configured DN-valued membership attribute. Follow group references only when nested membership is enabled, remaining within the configured group search scope. Use parsed LDAP DN equality and a visited set; do not compare DNs using ad hoc string normalization. + +For AD nested membership, use `LDAP_MATCHING_RULE_IN_CHAIN` where supported and enabled; its recursive link rule is specified by [Microsoft](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/1e889adc-b503-4423-8985-c28d5c7d4887). The optimization must preserve the configured scope and resource limits. Use bounded traversal instead when disabled or when the server definitively reports the operation unsupported. Do not retry arbitrary directory errors as a different query strategy. + +For OpenLDAP nested membership, traverse supported DN-valued group memberships with depth, visited-group, time, and result limits. Detect cycles. For AD member retrieval, handle ranged attributes if a traversal reads large member lists. Primary-group SID resolution and membership outside the configured group scope are excluded from this first version and must be stated in the operator guide. + +Return no partial authorization decision when a query, referral, pagination boundary, depth bound, or result limit prevents establishing complete membership. Deny the attempted validation and preserve the distinction between an outage and a confirmed empty group set. Do not erase stored grants merely because a directory transaction failed. + +Mapping creation, replacement, disablement, and deletion require `rbac:admin`, as do directory search and diagnostics. Preserve the application's existing page-level management guard and enforce API permissions independently. Search and mapping are separate operations; viewing search results never imports users or assigns roles. + +On a mapping edit, increment a database mapping revision and invalidate affected validation state. Removal must withdraw that mapping's materialized grants transactionally, with authorization revision changes visible to all processes. New mappings force fresh membership validation before granting access. An in-flight validation must compare its starting revision with the current revision before committing, so it cannot resurrect a removed grant. + +## Session freshness and revocation + +Add signed authentication context to access and refresh tokens: provider, identity ID, and directory ID for LDAP. Resolve the identity from the database and verify it belongs to the token's user; token context cannot select arbitrary accounts or endpoints. Rotation retains the same context. Local and Entra behavior remains independent of directory availability. + +Every LDAP login establishes fresh directory state. Every refresh forces a fresh check, with only concurrent in-flight checks coalesced. Other authenticated activity may use the last successful check for at most `LDAP_REVALIDATION_INTERVAL_SECONDS`, measured from the start of the directory read to avoid extending freshness by a slow transaction. At the deadline, stop delivering protected data or authorizing new operations until a fresh check succeeds. + +Revalidation uses the lookup identity to find the immutable subject, evaluate status, refresh profile, and resolve mapped memberships. It never rebinds as the user. Persist successful validation state and mapping revision in the database. Coordinate concurrent checks through bounded leases/fencing and in-process single-flight. Expired or failed work cannot overwrite a newer result or extend a successful timestamp. Use database time for cross-process timestamps and lease checks. + +| Outcome | Required behavior | +| --- | --- | +| Eligible user with explicit roles | Reconcile LDAP grants and profile atomically; continue | +| Group removal with remaining manual/other mapped roles | Remove lost grants; continue with reduced permissions | +| No remaining explicit role | Reject protected access and revoke LDAP sessions | +| User deleted, observably disabled/expired, or locally suspended | Reject access and revoke LDAP sessions; never reactivate local suspension | +| Network/TLS/search error or exceeded resolution limit | Do not advance freshness or erase grants; block LDAP access once freshness expires | +| Directory recovery after transient failure | Existing otherwise valid sessions may resume after a successful fresh check | +| Positive revocation followed by directory recovery | Require a new login; previously revoked tokens remain invalid | + +Use existing account-wide `session_version` for LDAP-only accounts when positively revoked. Profile refreshes must not accidentally trigger session revocation. Permission changes must invalidate effective permission caches, even when sessions remain valid. + +Connect the common eligibility service to ordinary REST middleware, refresh, SSE revalidation, MCP authorization, and console websocket checks. The console path currently checks `ConsoleSessionManager.assertSessionAuthorized`, so JWT middleware alone is insufficient. Close or stop protected delivery on stale/invalid authorization for each transport. Already dispatched infrastructure jobs are not automatically cancelled; authorization is checked before new actions and output delivery. + +No background full-directory polling is needed. Active connections drive periodic checks; an idle HTTP session is checked when next used. Request coalescing and bounded concurrency prevent the existing frequent stream checks from becoming frequent LDAP queries. + +Deploy the token-context change with an intentional one-time session invalidation and required reauthentication. Do not guess a legacy token's provider from email or from whichever linked identity happens to be present. Issue provider-bound tokens for local and Entra login as part of the same release. + +## HTTP and frontend contracts + +All routes below are proposed except existing provider discovery and token refresh. Use existing async route helpers, request validation, typed errors, audit infrastructure, and RBAC middleware. + +| Method and path | Access | Contract | +| --- | --- | --- | +| `GET /api/auth/providers` | Public | Add LDAP enabled/display/help metadata; expose no hostnames, search bases, credentials, or directory diagnostics | +| `POST /api/auth/ldap/login` | Public, rate limited | `{ username, password }`; same successful authentication DTO as local login | +| `POST /api/auth/refresh` | Existing refresh contract | Retain provider context and force LDAP verification for LDAP refresh tokens | +| `GET /api/auth/ldap/groups` | `rbac:admin` | Bounded `query` and opaque pagination cursor; selected group metadata only | +| `GET /api/auth/ldap/mappings` | `rbac:admin` | List mappings with roles and current/stored group labels | +| `POST /api/auth/ldap/mappings` | `rbac:admin` | Persist a verified group-subject/role mapping | +| `PUT /api/auth/ldap/mappings/:id` | `rbac:admin` | Change enabled state or role; verify directory/group ownership | +| `DELETE /api/auth/ldap/mappings/:id` | `rbac:admin` | Remove mapping and its attributable grants transactionally | +| `POST /api/auth/ldap/test` | `rbac:admin`, rate limited | Test configured TLS/lookup and optionally an exact user/group lookup; accept no user password or arbitrary connection overrides | + +Administrative cursors must be bound to the current directory/configuration and filter, bounded in lifetime and opaque to clients. Group creation can map several roles through separate unique mapping records. Mapping administration may show stored mappings during an outage, but cannot verify new directory identities until connectivity returns. + +Keep LDAP configured and visible in provider discovery during an outage; its login route can return temporary unavailability. Use `401` with a generic credential message for failed/ambiguous authentication, `403` for an authenticated but ineligible or unassigned user, `429` for rate/capacity limits, and `503` for directory unavailability or incomplete resolution. Return safe error codes; detailed directory reasons belong in restricted logs. All login failures must avoid disclosing whether a username exists. + +Reuse existing login throttling, but scope counters to provider, directory ID, and submitted login, with IP limits as well. A local username must not share a lockout counter with an LDAP username. Do not retry user bind failures across endpoints: a rejected credential must not multiply directory lockout attempts. + +The login page selects Local or the configured directory for password entry; Entra retains its redirect button. Keep token storage behavior in `auth.svelte.ts`. Show directory source and current directory login/display name in user administration. Render null contact emails safely in auth/user/group DTOs, filtering, search, dialogs, and tables. A missing email is not a broken profile. + +Diagnostics return per-stage status, timings, and safe error codes. Test both identity and eligibility visibility for an exact supplied user, without treating that lookup as proof of password authentication. Group diagnostics test direct/nested resolution for selected mapped groups. Redact passwords, token material, raw LDAP diagnostic strings, unnecessary personal fields, and raw connection configuration from responses. Diagnostics use only configured endpoints so they do not become an arbitrary network probe. + +## Failure handling and operations + +Retry only transient connection establishment failures against configured equivalent endpoints, within the total deadline. Stop on certificate/hostname failures, rejected lookup credentials, invalid user credentials, policy denial, malformed data, or ambiguity. Do not follow LDAP referrals to unconfigured endpoints. Search references or partial results that affect authentication cause validation failure. + +Preserve local startup/setup and emergency administrator access during directory outages. Directory availability is a degraded component signal, not process liveness failure. Add a restricted readiness/diagnostic view and metrics or existing structured monitoring hooks for connection latency, validation latency, revalidation failures, limits, and failover. Public health responses must not disclose directory topology. + +Use structured logs with `{ component, operation }` and safe provider/directory identifiers. Audit successful/failed login, mapping mutations, manual entitlement edits, suspension, positive revocation, and effective entitlement changes. Avoid one audit event per unchanged five-minute check. Record IDs and reason codes rather than passwords or complete directory entries. Environment lookup credentials remain in the deployment secret boundary; never store another copy in the database. + +## Implementation sequence + +1. **Schema and identity boundaries:** Add migrations for provider-scoped identity uniqueness, source-owned grants, optional external contact email, local credential scope, profile fields, and validation coordination. Backfill existing accounts and Entra grants. Update DTOs and scoped email callers. Verify SQLite and PostgreSQL upgrades before building LDAP on these assumptions. +2. **Provider-neutral provisioning:** Refactor Entra-specific creation into a shared transactional primitive with explicit default-role policy. Keep Entra defaults/enrollment behavior and manual assignments intact. LDAP explicitly requests no default role and forbids linking/local password creation. +3. **Directory configuration and client:** Add configuration types/parser, presets, conditional validation, TLS, bounded read-only operations, immutable ID codecs, status policies, failover, and direct/nested group resolution. Add the dependency through the approved package-install path. +4. **Authorization administration:** Add mapping persistence, restricted search/diagnostics/routes, source attribution, revision invalidation, and role-management UI controls. +5. **Provider-bound authentication:** Implement LDAP login and common session eligibility, token context, shared dependency wiring, refresh checks, and transport integration. Introduce the one-time session invalidation in the release migration. +6. **Frontend and operator documentation:** Add provider selection, directory-owned profile behavior, null-safe contact fields, examples, and documented policy/diagnostic behavior. Update `backend/.env.example`, `docs/configuration.md`, `docs/api.md`, `docs/openapi.yaml`, `docs/permissions-rbac.md`, and add `docs/integrations/ldap.md`. +7. **Acceptance and rollout:** Run migration, directory interoperability, revocation, RBAC, frontend, and regression coverage. Publish no support claim for real AD until tested against an actual AD environment. + +## Session execution plan + +These are ordered work packages, not estimates of context-window capacity. One session may complete several packages; a package may need several sessions. The design sections above remain authoritative. Record execution progress here so another agent can resume without conversation history. + +### Start and finish each session + +1. Read the current repository instructions, this package's prerequisites, its referenced design sections, and the latest handoff record. Check the actual branch, working tree, and prerequisite implementation before relying on recorded status. +2. Understand the affected architecture and callers before editing. Confirm current migration numbers, test locations, and package scripts from the repository. Preserve unrelated work. +3. Work within the selected package. Include the compatibility changes needed to keep local and Entra behavior working at every checkpoint. If a discovered dependency changes the package boundary, record it here before proceeding. +4. Run focused acceptance tests and relevant build/lint checks. Record exact commands and outcomes in the external command log. Update API/configuration contracts whenever an implemented route or variable changes, even when the full operator guide belongs to a later package. +5. Update the progress table and append a handoff entry before ending the session. Mark a package complete only when its acceptance criteria pass; missing AD/PostgreSQL evidence remains pending or blocked. Record pre-existing failures separately from regressions. + +Keep LDAP login unavailable until package 5B passes. Use the implementation's agreed configuration and wiring to enforce that boundary, without adding temporary bypasses or advertising unfinished authentication. A checkpoint must preserve existing functionality. + +### Package 1 Identity and schema + +**Prerequisites:** None. Read [Identity and database design](#identity-and-database-design) and the migrations, identity, profile, and authorization rows in [Acceptance tests](#acceptance-tests). + +**Scope and files:** Own forward SQLite/PostgreSQL migrations, identity uniqueness, external email nullability, local credential scope, source-owned grants, mapping/validation records, indexes, views, and revision triggers. Update affected queries and nullable DTO consumers together. Main surfaces: `backend/src/database/migrations/`, `UserService.ts`, `PermissionService.ts`, `AuthenticationService.ts` DTOs, Entra grant reconciliation, and frontend user/email consumers. + +**Exclusions:** LDAP network operations, login routes, and token-format changes. Validation tables may exist without enabling session checks. + +**Acceptance:** Fresh and upgraded databases preserve local and Entra identities, explicit enrollments, permissions, and referential integrity on both adapters. External missing/duplicate contact emails work; local uniqueness remains enforced. Existing Entra synchronization uses the new provenance model correctly. Null email renders safely. + +**Checks:** Focused migration, authorization-state, concurrency, user/Entra provisioning and frontend nullability tests; backend/frontend builds and applicable lint/component checks. + +**Handoff:** Record migration numbers, identity/grant keys, scoped email APIs, backfill assumptions, and exact upgrade fixtures/results. Existing writers and readers must agree on the schema before this package is complete. + +### Package 2 Shared provisioning + +**Prerequisites:** Package 1. Read [Authentication services and login flow](#authentication-services-and-login-flow) and the provisioning transaction rules in [Identity and database design](#identity-and-database-design). + +**Scope and files:** Extract provider-neutral transactional provisioning from `backend/src/services/UserService.ts`; adapt `EntraIdService.ts` callers. Define immutable identity inputs, profile ownership, explicit default-role policy, conflict handling, and first-login concurrency. Enforce LDAP account ownership in user/password update routes. + +**Exclusions:** Live LDAP access and public LDAP authentication. Preserve existing Entra default-role and explicit enrollment semantics. + +**Acceptance:** Existing local/Entra flows pass. Service-level LDAP provisioning creates one account under concurrency, assigns no default role, preserves suspension/manual grants, and prevents local password attachment or implicit linking. + +**Checks:** Provisioning, Entra auth-flow/group-sync, user update, and password-boundary regressions; backend build/lint. + +**Handoff:** Record the shared provisioning API, transaction ownership, role-policy inputs, and all migrated callers. + +### Package 3 Directory configuration and service + +**Prerequisites:** Packages 1 and 2. Read [Environment configuration](#environment-configuration), [Authentication services and login flow](#authentication-services-and-login-flow), and [Group resolution and role administration](#group-resolution-and-role-administration). + +**Scope and files:** Add typed LDAP configuration through `backend/src/config/`, the reviewed dependency in `backend/package.json` and lockfile, and `LdapDirectoryService` under `backend/src/services/`. Implement TLS, lookup/user-bind isolation, status policies, immutable ID codecs, bounded searches, endpoint failover, and direct/nested membership. Add reproducible directory fixtures and update implemented configuration references. + +**Exclusions:** Role-mapping administration, Pabawi token issuance, and frontend login. Keep directory support callable through internal services/tests. + +**Acceptance:** Disabled LDAP leaves existing startup behavior intact. Invalid configuration fails; an unreachable configured directory permits local access. OpenLDAP fixtures verify both TLS modes, binding, eligibility, group classes, limits, and cleanup. AD behavior has protocol-level tests, with actual AD evidence explicitly deferred if unavailable. + +**Checks:** Configuration/client unit tests, real OpenLDAP integration tests, backend build/lint, and documentation contracts. + +**Handoff:** Record the pinned library release, service API, fixture commands, supported policy attributes, TLS/failover evidence, and real AD cases still outstanding. + +### Package 4 RBAC mapping administration + +**Prerequisites:** Packages 1 through 3. Read [Group resolution and role administration](#group-resolution-and-role-administration) and [HTTP and frontend contracts](#http-and-frontend-contracts). + +**Scope and files:** Implement mapping persistence, bounded directory group search, diagnostics, administrative routes, audit events, materialized-grant withdrawal, and cross-process revision invalidation. Main surfaces: `backend/src/services/`, `backend/src/routes/`, server/container wiring, and API documentation. Complete the backend contract here; mapping controls are owned by package 6. + +**Exclusions:** Public LDAP login, token changes, and bulk user import. + +**Acceptance:** Search/test/mapping endpoints enforce `rbac:admin`. Mapping edits preserve grants from other sources, invalidate stale validation state, and cannot be undone by an in-flight old revision. Outages and fabricated group identities produce the agreed failures without leaking credentials. + +**Checks:** Supertest permission/error cases, provenance and revision-race tests on both adapters, backend build/lint, and documentation contracts. + +**Handoff:** Record route/service contracts, mapping revision behavior, audit events, and frontend integration examples using synthetic IDs. + +### Package 5 Authentication and session enforcement + +Read [Session freshness and revocation](#session-freshness-and-revocation), [HTTP and frontend contracts](#http-and-frontend-contracts), and the freshness, concurrency, and transport acceptance rows. Split this package at the following checkpoints when needed. + +#### Package 5A Provider context and shared authentication wiring + +**Prerequisites:** Packages 1, 2, and 4. + +**Scope and files:** Add verified provider/identity context to token creation, validation, and rotation for existing authentication providers. Replace isolated authentication-service construction with shared configured dependencies. Main surfaces: `AuthenticationService.ts`, `EntraIdService.ts`, `authMiddleware.ts`, server/container wiring, and authentication routes. Add the intentional one-time session invalidation in the appropriate forward migration. + +**Exclusions:** Issuing LDAP tokens before 5B is complete. + +**Acceptance:** Local and Entra login/refresh remain functional with explicit context. Forged, mismatched, or invalidated context fails. The legacy-session transition requires reauthentication without guessing provider ownership. All relevant callers can reach the shared eligibility seam. + +**Checks:** Local/Entra login-refresh, revocation and context-binding tests; fresh/upgrade session invalidation on both adapters; backend build/lint. + +**Handoff:** Record token payload contracts, migration/session invalidation behavior, dependency wiring, and exact transport integration points remaining for 5B. + +#### Package 5B LDAP login and all transport checks + +**Prerequisites:** Packages 3, 4, and 5A. + +**Scope and files:** Implement `LdapAuthenticationService`, explicit login and provider discovery, forced refresh verification, persisted freshness/leases/fencing, grant/profile reconciliation, provider-scoped throttling, and revocation. Wire REST, `SessionAuthorization`, SSE, MCP, and console authorization to shared eligibility enforcement. + +**Exclusions:** Login UI and automatic cancellation of already dispatched infrastructure work. + +**Acceptance:** LDAP tokens are issued only after the complete credential/eligibility/role transaction. Every supported transport blocks stale state at the deadline. Refresh forces verification; failed work cannot extend freshness or resurrect grants. Positive revocation remains terminal while transient recovery follows the agreed policy. Local/Entra sessions remain independent of LDAP availability. + +**Checks:** HTTP login/refresh integration tests, fake-clock deadline tests, cross-process coordination and revision-race tests, plus REST/SSE/MCP/console revocation coverage. Run backend regressions, build/lint, and documentation contracts. + +**Handoff:** Record enforcement evidence for each transport, freshness/lease state transitions, throttling keys, outage/recovery behavior, and any remaining interoperability evidence. Package 5 is complete only when both checkpoints pass. + +### Package 6 Frontend and operator documentation + +**Prerequisites:** Packages 4 and 5B, including stable HTTP/DTO contracts. Read [HTTP and frontend contracts](#http-and-frontend-contracts), [Environment configuration](#environment-configuration), and [Failure handling and operations](#failure-handling-and-operations). + +**Scope and files:** Implement common provider discovery, explicit password-provider selection, role-mapping controls, restricted diagnostics, directory source labels, and directory-owned profile editing rules. Main surfaces: `LoginPage.svelte`, `auth.svelte.ts`, `entraIdAuth.svelte.ts`, role/user management pages and dialogs. Finish `docs/integrations/ldap.md`, configuration/env examples, API/OpenAPI, and RBAC documentation. + +**Exclusions:** Reworking the agreed backend identity/security contract or claiming unverified AD interoperability. + +**Acceptance:** Provider selection never falls through; valid short directory credentials reach LDAP; nullable email and read-only profile fields work throughout user management. Mapping and diagnostic controls respect API and page permissions. Local and Entra UI regressions pass. Operator instructions explain status visibility, exclusions, outages, restart, and upgrade reauthentication. + +**Checks:** Focused component/API integration tests, appropriate browser/E2E flows, frontend tests/build/lint, component checking, and documentation contracts. + +**Handoff:** Record UI/browser evidence, operator guide locations, actual implemented defaults, and any remaining end-to-end cases. + +### Package 7 Interoperability and rollout + +**Prerequisites:** Packages 1 through 6. Read the complete [Acceptance tests](#acceptance-tests), [Failure handling and operations](#failure-handling-and-operations), and [Completion criteria](#completion-criteria). + +**Scope and files:** Verify real OpenLDAP and AD behavior, both database adapters, multi-process races, failover, every transport, and existing local/Entra functionality. Fix failures in their owning modules with regression coverage. Finish deployment and upgrade instructions based on observed behavior. + +**Exclusions:** Production deployment, remote pushes, PR creation, destructive cleanup, or sharing real directory data without the confirmations required by repository instructions. + +**Acceptance:** Every acceptance row has passing evidence. Missing real AD or PostgreSQL access is a recorded blocker to completion, not a waived test. Operators can configure either supported directory from the guide and understand the intentional session invalidation. + +**Checks:** The full commands under [Commands for the implementation phase](#commands-for-the-implementation-phase), relevant E2E checks, real directory fixtures, and SQLite/PostgreSQL upgrade scenarios. Record unavailable tools and their effect on completion. + +**Handoff:** Record release readiness, exact environment/version evidence without secrets or personal records, unresolved blockers, and the deployment procedure. + +### Progress and handoff records + +Update this table as work proceeds. Status values: `pending`, `in_progress`, `blocked`, or `complete`. A package can remain `in_progress` across several agent sessions. + +| Package | Status | Completion commit or working tree reference | Latest handoff | +| --- | --- | --- | --- | +| 1 Identity and schema | complete | Branch `151`, base `2c23a95`, uncommitted migration 031 and consumers | [2026-10-21 Codex](#handoff-2026-10-21-codex-package-1) | +| 2 Shared provisioning | pending | Not started | None | +| 3 Directory configuration and service | pending | Not started | None | +| 4 RBAC mapping administration | pending | Not started | None | +| 5A Provider context and wiring | pending | Not started | None | +| 5B LDAP login and transport enforcement | pending | Not started | None | +| 6 Frontend and operator documentation | pending | Not started | None | +| 7 Interoperability and rollout | pending | Not started | None | + +Append a record using the following fields after each implementation session. Use an actual commit hash when available, otherwise identify the branch/base and changed paths explicitly. Preserve prior records and correct outdated findings with a new entry. + +```text +Date and agent: +Package and checkpoint: +Branch, base commit, completion commit or uncommitted paths: +Completed scope and changed interfaces: +Verification: exact commands, outcomes, and external log reference: +Pre-existing failures: +Remaining work and blockers: +Decisions or discoveries affecting the next package: +Next action and acceptance criterion still to satisfy: +``` + +For a new agent session, use: "Read AGENTS.md and docs/internal/plans/ldap-authentication.md. Resume package from its latest handoff. Complete its scope and acceptance checks, then update the progress table and append a handoff record. Follow the current command-log instructions." + +## Acceptance tests + +Use existing Vitest, Supertest, migration fixtures, security tests, and frontend conventions. Place backend unit tests under `backend/test/unit/`, HTTP flows under `backend/test/integration/`, revocation cases under `backend/test/security/`, and database upgrade/concurrency tests under `backend/test/database/`. Co-locate Svelte tests with their components. + +| Area | Required evidence | +| --- | --- | +| Configuration | Disabled LDAP requires no credentials; enabled invalid configuration fails; malformed JSON, DNs, attributes, filters, TLS mode, missing CA files, and inconsistent anonymous settings fail | +| TLS and failover | Trusted LDAPS and StartTLS succeed; untrusted CA, hostname mismatch, forbidden wildcard, failed upgrade, and plaintext attempts fail; connection failover works without credential replay | +| Credentials | Empty passwords never bind; correct credentials succeed; wrong credentials, zero/multiple matches, missing immutable IDs, injection input, partial searches, and timeouts issue no tokens | +| Identity | Renamed/moved users retain identity; reused names/DNs do not inherit accounts; duplicate/missing external emails work; local names/emails retain their rules; concurrent logins create one account | +| Profiles | Directory changes refresh safely; missing names/email render; profile sync does not revoke valid sessions or undo local suspension; LDAP password/profile writes fail server-side | +| Authorization | No default role; zero-role user gets no token; manual assignment enables subsequent login; multiple mappings union roles; one removed mapping preserves other provenance | +| Groups | Direct and nested OpenLDAP/AD membership, cycle detection, scope, depth/result limits, group rename/recreation, and unsupported AD matching-rule behavior | +| Status | AD observable disabled/expired/locked states; OpenLDAP positive policy including missing attributes; bind-only limitations documented | +| Freshness | Fake-clock tests at the exact deadline; refresh forces verification; outage does not extend freshness; transient recovery resumes valid sessions; positive revocation remains terminal | +| Concurrency | Cross-process leases, fencing, stale completion, mapping-revision races, and simultaneous refresh cannot restore obsolete grants or timestamps | +| Transports | REST, refresh, SSE, MCP, and console websocket reject stale/invalid LDAP state while local and Entra remain independent | +| Administration | Every search/mapping/test endpoint rejects missing permissions; request fields cannot override endpoints or fabricate group identity; mutations audit and invalidate permissions | +| Migrations | Fresh and upgraded SQLite/PostgreSQL preserve users, Entra enrollments, grants, foreign keys, triggers/views, uniqueness, and intentional session invalidation | +| UI | Provider selection never falls through; LDAP accepts directory-valid short credentials; directory fields are read-only; null email, mappings, empty results, and outages render correctly | + +Run real OpenLDAP integration tests for both TLS modes and supported group classes with an explicit eligibility policy. Test real AD for GUID handling, account state, nested matching rules, large/ranged membership, and failover. A mock LDAP server or Samba-only result is insufficient evidence of real AD compatibility. + +### Commands for the implementation phase + +Run from the repository root unless stated otherwise. These are planned commands, not commands executed while writing this document. Log commands according to the current repository instructions in `~/.agents/logs/pabawi.jsonl`, outside the repository. Create the log directory/file if missing, append one JSON object per line, redact secrets, and record command outcomes after completion. Skip trivial read-only commands as specified in AGENTS.md. + +```bash +# Add the backend dependency through the required package review wrapper. +socket npm install ldapts --workspace=backend + +# Run focused new tests first, using their actual implementation filenames. +# Then check the complete workspace and documentation contracts. +npm run test --workspace=backend +npm run test --workspace=frontend +npm run build +npm run lint +npm run check:components +node --test scripts/documentation/contracts.test.mjs +bash scripts/quality/secret-scan.sh +git diff --check +``` + +Use a reproducible directory test fixture with its own documented startup and cleanup commands during implementation. Scan downloaded fixture artifacts with ClamAV after use as required by the project instructions. Do not commit directory secrets, real user records, or production CA private keys. The CA bundle contains public certificates only. + +## Completion criteria + +The implementation is complete when both supported directory types authenticate and authorize through the agreed configuration, users can be managed without identity collisions or implicit linking, directory eligibility controls every supported transport within the freshness bound, migrations preserve existing local/Entra behavior, and the acceptance matrix passes on SQLite and PostgreSQL. The operator guide must state observable status limitations, group scope exclusions, restart requirements, outage behavior, and the one-time reauthentication required on upgrade. + + +## Handoff 2026-10-21 Codex package 1 + +**Date and agent:** 2026-10-21, Codex. + +**Package and checkpoint:** Package 1, identity and schema, complete. LDAP network access, provider discovery, login routes, token context, and runtime eligibility enforcement remain assigned to later packages. + +**Branch, base commit, completion commit or uncommitted paths:** Branch `151`, base `2c23a95b81a2492d6dec5f3a76ea0b3afe06e76f`. No completion commit was created. The plan was already untracked at the start of this session. All implementation changes remain in the working tree: + +```text +backend/src/database/migrations/031_external_identity_boundaries.postgres.sql +backend/src/database/migrations/031_external_identity_boundaries.sqlite.sql +backend/src/services/AuthenticationService.ts +backend/src/services/EntraIdService.ts +backend/src/services/GroupService.ts +backend/src/services/UserService.ts +backend/test/UserService.password.test.ts +backend/test/database/BatchLifecycleMigration.test.ts +backend/test/database/external-identity-boundaries.test.ts +backend/test/database/migration-integration.test.ts +backend/test/database/rbac-schema.test.ts +backend/test/database/sso-concurrency.test.ts +backend/test/properties/EntraIdAuthCode.property.test.ts +backend/test/properties/EntraIdCallback.property.test.ts +backend/test/properties/EntraIdGroupSync.property.test.ts +backend/test/properties/EntraIdProvisioning.property.test.ts +backend/test/properties/user/email-uniqueness.property.test.ts +backend/test/services/AuthenticationService.bruteforce.test.ts +backend/test/unit/services/EntraIdService.test.ts +docs/api.md +docs/internal/plans/ldap-authentication.md +docs/openapi.yaml +frontend/src/components/GroupDetailDialog.svelte +frontend/src/components/UserDetailDialog.svelte +frontend/src/components/user-contact-nullability.test.ts +frontend/src/lib/auth.svelte.ts +frontend/src/lib/auth.test.ts +frontend/src/lib/permission-state.test.ts +frontend/src/pages/UserManagementPage.svelte +``` + +**Completed scope and changed interfaces:** + +- Added forward migration `031_external_identity_boundaries.sqlite.sql` and its PostgreSQL counterpart. Fresh schemas and populated migration-030 upgrades retain user IDs, identity IDs, explicit Entra enrollments, original profile data, session versions, manual/group assignments, revoked tokens, audit links, and journal links. Historic migration-016 upgrade fixtures also pass through 031. +- Identity uniqueness is now `(provider, issuer, subject)`. Added composite parent keys to enforce grant-to-user ownership and LDAP metadata-to-directory ownership. Mutable LDAP login/DN locators are stored in `ldap_identity_metadata`; they are deliberately nonunique and are never identity keys. +- `users.local_auth_enabled` is the local account/credential scope. Backfill sets it to 1 when a password hash exists and 0 otherwise, including explicitly enrolled Entra users with local passwords. External-only rows require a null password hash. Local rows require nonempty contact email, with uniqueness enforced by the partial `idx_users_local_email` index. Existing usernames are preserved; local creation reserves the case-insensitive `ldap:` prefix. New Entra creation explicitly uses scope 0 and stores absent email as null. +- Added nullable `display_name`; backend/auth/frontend user DTOs expose `displayName: string | null` and `email: string | null`. Internal password hashes are consistently nullable. Group member contact email is nullable. User filtering, user details, and group member rendering handle absent contact email. API/OpenAPI documentation describes these implemented fields. +- Removed ambiguous singular email lookup. `UserService.findLocalByEmail(email)` returns the unique local-scoped account, while `findAllByEmail(email)` returns every contact match. Entra provisioning rejects any existing email match without linking. Entra creation serializes its collision checks using the existing default-role configuration row inside its transaction; independent-connection tests cover simultaneous subjects sharing one email. +- `federated_user_roles` now has primary key `(identity_id, role_id, source_key)`. Group-derived LDAP grants also reference `mapping_id` and `directory_id`, with composite foreign keys binding the role, mapping, directory, identity, and user. Existing materialized Entra grants are backfilled to each existing Entra identity for that user with source key `legacy`. Detached historical grants with no remaining Entra identity are preserved in manual `user_roles`, with a database timestamp, rather than discarded. Existing migration-027 legacy markers retain their established first-reconciliation cleanup semantics. +- `EntraIdService.syncGroupRoles(identityId, groups)` now requires an Entra identity from the configured issuer, deletes only that identity's grants, and stores `group:` source keys. Multiple groups granting one role retain separate provenance. The callback resolves its authenticating identity before reconciliation. Manual assignments and grants owned by other identities survive. `effective_user_roles` retains its UNION deduplication; existing PermissionService and token role queries already consume this view, so no separate permission-query rewrite was needed. +- Added `ldap_directory_state`, `external_group_mappings`, `ldap_validation_state`, and `ldap_validation_leases`. Mapping uniqueness is `(directory_id, group_subject, role_id)`. Mapping mutation triggers increment persisted directory revision, invalidate directory validation timestamps, and change authorization revision on both adapters. A BEFORE UPDATE trigger withdraws attributable grants before a role/scope composite-key edit; AFTER triggers handle revision changes. Deletion cascades only attributable grants. Validation timestamps/lease expiry are Unix milliseconds in BIGINT fields; generation fields are nonnegative BIGINTs. PostgreSQL returns BIGINT values as strings through the current adapter. Lease/fencing and freshness algorithms are still package 5B work. +- SQLite rebuilds use the existing runner's foreign-key suspension, atomic transaction, and pre-commit foreign-key check. Application indexes, user/session triggers, external-role revision triggers, and the effective-role view are recreated. Failed rebuild rollback, restored enforcement, profile updates without revocation, sensitive-field revocation, mapping rollback, role edits, identity cascade cleanup, and cross-connection cache invalidation are covered. +- Compatibility adjustment: explicitly administrated password attachment for an existing Entra-only account enables its local scope atomically. LDAP identities cannot acquire local passwords through that path. Complete LDAP profile ownership and shared provider-neutral provisioning remain package 2. + +**Verification: exact commands, outcomes, and external log reference:** + +Commands ran from the repository root. The append-only command log is `~/.agents/logs/pabawi.jsonl`. PostgreSQL used the already-present `postgres:17` image, version 17.11; SQLite was 3.52.0. No dependencies or fixture artifacts were downloaded. Host Node was 26.8.1; the repository declares Node >=24.21.0 and <25, so the supported-engine release check remains separate evidence. + +- `docker run --detach --name pabawi-ldap-p1-postgres --pull never -e POSTGRES_HOST_AUTH_METHOD=trust -p 127.0.0.1::5432 postgres:17`: isolated local test server, loopback port 63167. Fresh acceptance databases avoided checksum reuse while 031 was being finalized. The fixture was stopped with `docker stop pabawi-ldap-p1-postgres` after final verification; the stopped container was retained. +- `TEST_DATABASE_URL=postgresql://postgres@127.0.0.1:63167/ldap_package1_verified npm run test --workspace=backend > /tmp/pabawi-ldap-p1-backend-final.log 2>&1 && npm run build:backend > /tmp/pabawi-ldap-p1-build-final.log 2>&1`: PASS, 239 test files passed, one skipped; 3863 tests passed, two skipped, one todo. The backend artifact includes the final migration files. +- `TEST_DATABASE_URL=postgresql://postgres@127.0.0.1:63167/ldap_package1_final npm run test --workspace=backend -- test/database/external-identity-boundaries.test.ts`: PASS after the PostgreSQL BEFORE UPDATE fix, 17 tests. The final full run also includes these tests against the final timestamp SQL. +- `npm run test --workspace=frontend > /tmp/pabawi-ldap-p1-frontend-tests-final.log 2>&1`: PASS, 60 files and 1046 tests, including null email rendering/filtering and user/group detail dialogs. +- `npm run build && npm run check:components > /tmp/pabawi-ldap-p1-components.log 2>&1`: PASS, both production builds and zero component errors. Subsequent `npm run build:backend && npm run lint && npm run check:components > /tmp/pabawi-ldap-p1-components-acceptance.log 2>&1 && git diff --check` also passed; frontend source did not change after its successful production build. Vite retained its existing large-chunk warning. +- `node --test --test-name-pattern='every declared REST|API guide|OpenAPI version|public exchanges|configuration inventory|architecture registry' scripts/documentation/contracts.test.mjs`: PASS, six contracts covering routes, API/OpenAPI, auth boundaries, configuration, and architecture. +- Changed/new-file `detect-secrets scan` with the existing pre-commit environment, followed by a comparison against reviewed baseline hashes: PASS, zero new unreviewed findings. Exact file arguments and comparison command are in the external log. Synthetic credential fixtures are explicitly annotated. The baseline was not changed. +- `git diff --check`: PASS. The command log parses as JSON Lines. + +**Pre-existing failures:** + +- Unfiltered `node --test scripts/documentation/contracts.test.mjs` reports six passes and one failure: package metadata is 1.5.1, but CHANGELOG.md lacks a dated 1.5.1 entry and begins with 1.6.0 Unreleased. The relevant version/changelog files match the starting commit. +- `bash scripts/quality/secret-scan.sh` initially could not find detect-secrets on PATH. Using `PATH=/Users/al/.cache/pre-commit/repovdso_3ip/py_env-python3/bin:$PATH bash scripts/quality/secret-scan.sh` runs the scanner and reports four pre-existing findings across unchanged `backend/package.json`, `backend/src/cli/resetUserPassword.ts`, and `backend/test/unit/cli/resetUserPassword.test.ts`. These files match HEAD; the LDAP change adds none. +- One repeated full backend run returned an intermittent 404 in the unchanged `test/security/workload-limits.test.ts`. `npm run test --workspace=backend -- test/security/workload-limits.test.ts` passed all five tests in isolation, and the subsequent final complete run passed. No unrelated workload-limit code was modified. + +**Remaining work and blockers:** No package-1 acceptance blocker remains. The unrelated release-documentation and tracked secret-scan failures above remain unresolved. Directory interoperability, supported-engine release evidence, runtime mapping administration, and session enforcement belong to later packages. No LDAP authentication is advertised or enabled. + +**Decisions or discoveries affecting the next package:** Use provider `ldap` and stable directory ID as issuer when creating LDAP identities. Reserve deterministic internal usernames beneath `ldap:` and use immutable subjects, not DN or login. Preserve the explicit local scope and the scoped email APIs. Entra's default role remains a manual `user_roles` assignment, and its legacy-marker behavior is unchanged. Mapping updates already withdraw old grants and invalidate persisted state through database triggers; callers must use a transaction and later add revision/fencing comparisons rather than relying only on cached permissions. Existing sessions are preserved by 031; intentional release invalidation remains package 5A. Validation and lease tables exist without any enabled runtime LDAP enforcement. + +**Next action and acceptance criterion still to satisfy:** Start package 2. Extract shared transactional provisioning, implement deterministic immutable LDAP account creation without default roles or implicit linking, preserve suspension/manual grants and Entra enrollment behavior, and enforce complete LDAP profile/password ownership. Verify concurrent first login creates one account, zero-role LDAP provisioning issues no tokens, and local/Entra regressions still pass. diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 0b4122fd..a7b76ac4 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -4848,6 +4848,15 @@ components: user: type: object description: User DTO, excludes password hash + properties: + email: + type: string + nullable: true + description: Contact email, not an identity key. May be shared by external accounts. + displayName: + type: string + nullable: true + description: Directory display name when available, separate from given name and surname. required: - token - refreshToken diff --git a/frontend/src/components/GroupDetailDialog.svelte b/frontend/src/components/GroupDetailDialog.svelte index 24ba5595..77dd18bb 100644 --- a/frontend/src/components/GroupDetailDialog.svelte +++ b/frontend/src/components/GroupDetailDialog.svelte @@ -17,7 +17,7 @@ interface UserDTO { id: string; username: string; - email: string; + email: string | null; firstName: string; lastName: string; } @@ -341,7 +341,7 @@ {member.username}

- {member.firstName} {member.lastName} • {member.email} + {member.firstName} {member.lastName} • {member.email ?? 'Not provided'}

+
{ event.preventDefault(); void run(() => search()); }} class="space-y-2"> + + + +
+ {#if searched && groups.length === 0}

No directory groups found.

{/if} + {#if groups.length} +
{ event.preventDefault(); void run(create); }} class="space-y-2"> + + + {#if !roleId} + + + {/if} + +
+ {/if} + {#if cursor}{/if} + +

Stored group mappings

+ {#if visibleMappings.length === 0}

No directory mappings for this role selection.

{/if} + + +

Restricted directory diagnostics

+

Uses the configured lookup account. This does not verify a user password or sign the user in.

+
{ event.preventDefault(); void run(diagnose); }} class="space-y-2"> + + +
+ Check membership in enabled mapped groups (up to 20) + {#each diagnosticGroups as mapping (mapping.groupSubject)} + + {/each} +
+ +
+ {#if busy}

Directory operation in progress...

{/if} + {#if report} +
+

Lookup diagnostic result. No password authentication performed.

+ + {#if report.groupSubjects} +

Matched selected groups: {report.groupSubjects.length}

+ + {/if} +
+ {/if} + +{/if} diff --git a/frontend/src/components/LdapAdministration.test.ts b/frontend/src/components/LdapAdministration.test.ts new file mode 100644 index 00000000..457dec1b --- /dev/null +++ b/frontend/src/components/LdapAdministration.test.ts @@ -0,0 +1,127 @@ +import { beforeEach, describe, expect, it, vi } from 'vitest'; +import { fireEvent, render, screen, waitFor } from '@testing-library/svelte'; +import LdapAdministration from './LdapAdministration.svelte'; +import { authManager } from '../lib/auth.svelte'; +import * as ldap from '../lib/ldapApi'; + +const guard = vi.hoisted(() => ({ admin: true })); +vi.mock('../lib/auth.svelte', () => ({ authManager: { get isAdmin() { return guard.admin; }, hasPermission: vi.fn(() => true) } })); +vi.mock('../lib/authProviders.svelte', () => ({ authProviders: { ldap: { name: 'Corporate directory' } } })); +vi.mock('../lib/api', () => ({ get: vi.fn().mockResolvedValue({ + roles: [{ id: 'viewer', name: 'Viewer' }, { id: 'operator', name: 'Operator' }], pagination: { totalPages: 1 }, +}) })); +vi.mock('../lib/ldapApi', () => ({ + listLdapMappings: vi.fn(), searchLdapGroups: vi.fn(), createLdapMapping: vi.fn(), + updateLdapMapping: vi.fn(), removeLdapMapping: vi.fn(), diagnoseLdap: vi.fn(), +})); + +const subject = '00112233-4455-6677-8899-aabbccddeeff'; +const mapping: ldap.LdapMapping = { id: 'mapping', directoryId: 'corporate', groupSubject: subject, + groupName: 'Operators', groupDn: 'cn=operators,dc=example,dc=test', + roleId: 'viewer', roleName: 'Viewer', enabled: true, source: 'ldap' }; + +beforeEach(() => { + vi.clearAllMocks(); + guard.admin = true; + vi.mocked(authManager.hasPermission).mockReturnValue(true); + vi.mocked(ldap.listLdapMappings).mockResolvedValue({ items: [mapping] }); + vi.mocked(ldap.searchLdapGroups).mockResolvedValue({ items: [], nextCursor: null }); +}); + +async function ready(): Promise { + await screen.findByText('Operators to Viewer: Enabled'); + await waitFor(() => expect((screen.getByRole('button', { name: 'Search groups' }) as HTMLButtonElement).disabled).toBe(true)); + await waitFor(() => expect((screen.getByRole('button', { name: 'Reload mappings' }) as HTMLButtonElement).disabled).toBe(false)); +} + +describe('LDAP role mapping administration', () => { + it.each(['page', 'permission'])('does no directory work when the %s guard denies access', async gate => { + if (gate === 'page') guard.admin = false; + else vi.mocked(authManager.hasPermission).mockReturnValue(false); + render(LdapAdministration); + expect(screen.queryByRole('region', { name: 'LDAP administration' })).toBeNull(); + expect(ldap.listLdapMappings).not.toHaveBeenCalled(); + }); + + it('renders empty search results without discarding stored mappings', async () => { + render(LdapAdministration); + await ready(); + await fireEvent.input(screen.getByLabelText('Search directory groups'), { target: { value: 'absent' } }); + await fireEvent.click(screen.getByRole('button', { name: 'Search groups' })); + expect(await screen.findByText('No directory groups found.')).toBeTruthy(); + expect(screen.getByText('Operators to Viewer: Enabled')).toBeTruthy(); + }); + + it('retains the searched filter with its cursor and creates a mapping using only immutable IDs', async () => { + vi.mocked(ldap.searchLdapGroups).mockResolvedValueOnce({ + items: [{ subject, dn: mapping.groupDn, name: mapping.groupName }], nextCursor: 'opaque', + }).mockResolvedValueOnce({ items: [], nextCursor: null }); + render(LdapAdministration); + await ready(); + await fireEvent.input(screen.getByLabelText('Search directory groups'), { target: { value: 'op' } }); + await fireEvent.click(screen.getByRole('button', { name: 'Search groups' })); + await screen.findByLabelText('Directory group'); + await fireEvent.input(screen.getByLabelText('Search directory groups'), { target: { value: 'edited' } }); + await fireEvent.click(screen.getByRole('button', { name: 'More groups' })); + expect(ldap.searchLdapGroups).toHaveBeenLastCalledWith('op', 'opaque'); + await waitFor(() => expect((screen.getByLabelText('Directory group') as HTMLSelectElement).disabled).toBe(false)); + await fireEvent.change(screen.getByLabelText('Directory group'), { target: { value: subject } }); + await fireEvent.change(screen.getByLabelText('Pabawi role'), { target: { value: 'operator' } }); + await fireEvent.click(screen.getByRole('button', { name: 'Create mapping' })); + expect(ldap.createLdapMapping).toHaveBeenCalledExactlyOnceWith(subject, 'operator'); + }); + + it('supports role replacement and outage-safe disablement, preserving labels on failure', async () => { + render(LdapAdministration); + await ready(); + await fireEvent.change(screen.getByLabelText('Mapped role'), { target: { value: 'operator' } }); + expect(ldap.updateLdapMapping).toHaveBeenLastCalledWith('mapping', { roleId: 'operator' }); + await waitFor(() => expect((screen.getByRole('button', { name: /Disable mapping/ }) as HTMLButtonElement).disabled).toBe(false)); + vi.mocked(ldap.updateLdapMapping).mockRejectedValueOnce(new Error('LDAP directory operation failed')); + await fireEvent.click(screen.getByRole('button', { name: /Disable mapping/ })); + expect(ldap.updateLdapMapping).toHaveBeenLastCalledWith('mapping', { enabled: false }); + expect((await screen.findByRole('alert')).textContent).toContain('LDAP directory operation failed'); + expect(screen.getByText('Operators to Viewer: Enabled')).toBeTruthy(); + }); + + it('requires confirmation for removal and only removes the selected mapping', async () => { + vi.spyOn(window, 'confirm').mockReturnValue(false); + render(LdapAdministration); + await ready(); + await fireEvent.click(screen.getByRole('button', { name: /Remove mapping/ })); + expect(ldap.removeLdapMapping).not.toHaveBeenCalled(); + vi.mocked(window.confirm).mockReturnValue(true); + await fireEvent.click(screen.getByRole('button', { name: /Remove mapping/ })); + expect(ldap.removeLdapMapping).toHaveBeenCalledExactlyOnceWith('mapping'); + }); + + it('shows failed stages and sends exact lookup input with selected mapped group subjects', async () => { + vi.mocked(ldap.diagnoseLdap).mockResolvedValue({ authenticated: false, stages: [ + { stage: 'tls', status: 'passed', durationMs: 2 }, + { stage: 'eligibility', status: 'failed', durationMs: 3, code: 'INELIGIBLE' }, + ] }); + render(LdapAdministration); + await ready(); + await fireEvent.input(screen.getByLabelText('Exact directory username (optional)'), { target: { value: ' a ' } }); + await fireEvent.click(screen.getByLabelText('Operators')); + await fireEvent.click(screen.getByRole('button', { name: 'Run directory diagnostics' })); + expect(ldap.diagnoseLdap).toHaveBeenCalledExactlyOnceWith({ username: ' a ', groupSubjects: [subject] }); + expect(await screen.findByText('eligibility: failed (3 ms), INELIGIBLE')).toBeTruthy(); + expect(screen.getByText('Lookup diagnostic result. No password authentication performed.')).toBeTruthy(); + }); + + it('uses the current role when opened from its detail dialog', async () => { + vi.mocked(ldap.searchLdapGroups).mockResolvedValue({ items: [ + { subject, dn: mapping.groupDn, name: mapping.groupName }, + ], nextCursor: null }); + render(LdapAdministration, { roleId: 'viewer' }); + await ready(); + await fireEvent.input(screen.getByLabelText('Search directory groups'), { target: { value: 'op' } }); + await fireEvent.click(screen.getByRole('button', { name: 'Search groups' })); + await screen.findByLabelText('Directory group'); + expect(screen.queryByLabelText('Pabawi role')).toBeNull(); + await fireEvent.change(screen.getByLabelText('Directory group'), { target: { value: subject } }); + await fireEvent.click(screen.getByRole('button', { name: 'Create mapping' })); + expect(ldap.createLdapMapping).toHaveBeenCalledWith(subject, 'viewer'); + }); +}); diff --git a/frontend/src/components/RoleDetailDialog.svelte b/frontend/src/components/RoleDetailDialog.svelte index 5f8e3267..c21d2ce0 100644 --- a/frontend/src/components/RoleDetailDialog.svelte +++ b/frontend/src/components/RoleDetailDialog.svelte @@ -11,6 +11,8 @@ type PermissionResource, type PermissionAction, } from '../lib/permissions'; + import LdapAdministration from './LdapAdministration.svelte'; + import { authProviders } from '../lib/authProviders.svelte'; import LoadingSpinner from './LoadingSpinner.svelte'; interface Props { @@ -374,6 +376,10 @@ {/if} + {#if authManager.isAdmin && canManageEntitlements && authProviders.ldap?.enabled && roleId} + + {/if} +
- {#if entraIdAuth.isEntraIdEnabled} - + {#if authProviders.entraId?.enabled} +
@@ -167,8 +184,8 @@
- {#if entraIdAuth.isEntraIdEnabled} - + {#if authProviders.entraId?.enabled} +
@@ -182,7 +199,7 @@ {/if} - {#if entraIdAuth.providerDiscoveryError} + {#if authProviders.error}
@@ -192,7 +209,7 @@

- SSO availability could not be determined. You can still sign in with your local credentials. + Authentication provider availability could not be determined. You can still sign in with your local credentials.

@@ -202,8 +219,19 @@ {/if} - {#if !entraIdAuth.isExchangingCode} + {#if !entraIdAuth.isExchangingCode && (authProviders.local || authProviders.ldap?.enabled)}
+
+ + + {#if provider === 'ldap' && authProviders.ldapHelpUrl} + Directory sign-in help + {/if} +
@@ -217,7 +245,7 @@ autocomplete="username" required bind:value={username} - disabled={isSubmitting} + disabled={isSubmitting || authProviders.isDiscovering} class="appearance-none relative block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 placeholder-gray-500 dark:placeholder-gray-400 text-gray-900 dark:text-white rounded-md focus:outline-none focus:ring-primary-500 focus:border-primary-500 focus:z-10 sm:text-sm bg-white dark:bg-gray-800 disabled:opacity-50 disabled:cursor-not-allowed" placeholder="Enter your username" /> @@ -240,7 +268,7 @@ autocomplete="current-password" required bind:value={password} - disabled={isSubmitting} + disabled={isSubmitting || authProviders.isDiscovering} class="appearance-none relative block w-full px-3 py-2 border border-gray-300 dark:border-gray-600 placeholder-gray-500 dark:placeholder-gray-400 text-gray-900 dark:text-white rounded-md focus:outline-none focus:ring-primary-500 focus:border-primary-500 focus:z-10 sm:text-sm bg-white dark:bg-gray-800 disabled:opacity-50 disabled:cursor-not-allowed" placeholder="Enter your password" /> @@ -274,7 +302,7 @@
- {#if !checkingConfig && selfRegistrationAllowed} + {#if provider === 'local' && !checkingConfig && selfRegistrationAllowed}

Don't have an account? diff --git a/frontend/src/pages/LoginPage.test.ts b/frontend/src/pages/LoginPage.test.ts index d976f047..f964d588 100644 --- a/frontend/src/pages/LoginPage.test.ts +++ b/frontend/src/pages/LoginPage.test.ts @@ -1,15 +1,11 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; -import { render, screen } from '@testing-library/svelte'; +import { render, screen, fireEvent, waitFor } from '@testing-library/svelte'; vi.mock('../lib/entraIdAuth.svelte', () => ({ entraIdAuth: { - isEntraIdEnabled: false, - entraIdProviderName: 'Microsoft Entra ID', - providerDiscoveryError: false, isExchangingCode: false, exchangeError: null as string | null, isDiscovering: false, - discoverProviders: vi.fn().mockResolvedValue(undefined), handleSsoCallback: vi.fn().mockResolvedValue(false), clearExchangeError: vi.fn(), }, @@ -42,6 +38,14 @@ vi.mock('../lib/api', () => ({ getErrorGuidance: vi.fn(() => ({ guidance: undefined })), })); +vi.mock('../lib/authProviders.svelte', () => ({ + authProviders: { local: true, entraId: undefined as { enabled: boolean; name: string } | undefined, + ldap: undefined as { enabled: boolean; name: string; loginHelpUrl: string } | undefined, + ldapHelpUrl: null as string | null, error: false, isDiscovering: false, discover: vi.fn().mockResolvedValue(undefined) }, +})); + +import { authProviders } from '../lib/authProviders.svelte'; +import { authManager } from '../lib/auth.svelte'; import LoginPage from './LoginPage.svelte'; import { entraIdAuth } from '../lib/entraIdAuth.svelte'; @@ -49,13 +53,14 @@ describe('LoginPage', () => { beforeEach(() => { vi.clearAllMocks(); // Reset mock state - entraIdAuth.isEntraIdEnabled = false; - entraIdAuth.entraIdProviderName = 'Microsoft Entra ID'; - entraIdAuth.providerDiscoveryError = false; + authProviders.local = true; + authProviders.entraId = undefined; + authProviders.ldap = undefined; + authProviders.error = false; entraIdAuth.isExchangingCode = false; entraIdAuth.exchangeError = null; vi.mocked(entraIdAuth.handleSsoCallback).mockResolvedValue(false); - vi.mocked(entraIdAuth.discoverProviders).mockResolvedValue(undefined); + vi.mocked(authProviders.discover).mockResolvedValue(undefined); }); afterEach(() => { @@ -64,7 +69,7 @@ describe('LoginPage', () => { describe('SSO button conditional rendering', () => { it('shows SSO button when entraIdAuth.isEntraIdEnabled is true', () => { - entraIdAuth.isEntraIdEnabled = true; + authProviders.entraId = { enabled: true, name: 'Microsoft Entra ID' }; render(LoginPage); @@ -72,7 +77,7 @@ describe('LoginPage', () => { }); it('hides SSO button when entraIdAuth.isEntraIdEnabled is false', () => { - entraIdAuth.isEntraIdEnabled = false; + authProviders.entraId = undefined; render(LoginPage); @@ -82,19 +87,19 @@ describe('LoginPage', () => { describe('Provider discovery error', () => { it('shows warning when providerDiscoveryError is true', () => { - entraIdAuth.providerDiscoveryError = true; + authProviders.error = true; render(LoginPage); - expect(screen.getByText(/SSO availability could not be determined/)).toBeTruthy(); + expect(screen.getByText(/Authentication provider availability could not be determined/)).toBeTruthy(); }); it('does not show warning when providerDiscoveryError is false', () => { - entraIdAuth.providerDiscoveryError = false; + authProviders.error = false; render(LoginPage); - expect(screen.queryByText(/SSO availability could not be determined/)).toBeNull(); + expect(screen.queryByText(/Authentication provider availability could not be determined/)).toBeNull(); }); }); @@ -128,7 +133,7 @@ describe('LoginPage', () => { it('shows SSO button below error when entraId is enabled', () => { entraIdAuth.exchangeError = 'Something went wrong'; - entraIdAuth.isEntraIdEnabled = true; + authProviders.entraId = { enabled: true, name: 'Microsoft Entra ID' }; render(LoginPage); @@ -139,7 +144,7 @@ describe('LoginPage', () => { describe('Local login form always present', () => { it('shows local login form when SSO is disabled', () => { - entraIdAuth.isEntraIdEnabled = false; + authProviders.entraId = undefined; render(LoginPage); @@ -149,7 +154,7 @@ describe('LoginPage', () => { }); it('shows both SSO button and local login form when SSO is enabled', () => { - entraIdAuth.isEntraIdEnabled = true; + authProviders.entraId = { enabled: true, name: 'Microsoft Entra ID' }; render(LoginPage); @@ -159,3 +164,51 @@ describe('LoginPage', () => { }); }); }); + +describe('explicit password provider selection', () => { + beforeEach(() => { + vi.clearAllMocks(); + authProviders.local = true; + authProviders.ldap = { enabled: true, name: 'Corporate directory', loginHelpUrl: '' }; + authProviders.error = false; + entraIdAuth.isExchangingCode = false; + entraIdAuth.exchangeError = null; + vi.mocked(entraIdAuth.handleSsoCallback).mockResolvedValue(false); + vi.mocked(authProviders.discover).mockResolvedValue(undefined); + }); + + async function submit(username: string, password: string): Promise { + await fireEvent.input(screen.getByLabelText('Username'), { target: { value: username } }); + await fireEvent.input(screen.getByLabelText('Password'), { target: { value: password } }); + await fireEvent.submit(screen.getByRole('button', { name: /^sign in$/i }).closest('form')!); + } + + it('submits short LDAP credentials unchanged without falling through after denial', async () => { + render(LoginPage); + await waitFor(() => expect(authProviders.discover).toHaveBeenCalled()); + await fireEvent.change(screen.getByLabelText('Sign in using'), { target: { value: 'ldap' } }); + await submit(' a ', ' x '); + expect(authManager.login).toHaveBeenCalledExactlyOnceWith({ username: ' a ', password: ' x ' }, 'ldap'); + expect((screen.getByLabelText('Sign in using') as HTMLSelectElement).value).toBe('ldap'); + expect((screen.getByLabelText('Password') as HTMLInputElement).value).toBe(''); + }); + + it('keeps local validation and clears credentials when provider changes', async () => { + render(LoginPage); + await submit('a', 'x'); + expect(authManager.login).not.toHaveBeenCalled(); + expect(screen.getByText('Password must be at least 8 characters')).toBeTruthy(); + await fireEvent.change(screen.getByLabelText('Sign in using'), { target: { value: 'ldap' } }); + expect((screen.getByLabelText('Password') as HTMLInputElement).value).toBe(''); + expect(screen.queryByText('Password must be at least 8 characters')).toBeNull(); + }); + + it('rejects oversized UTF-8 directory inputs before submission', async () => { + render(LoginPage); + await fireEvent.change(screen.getByLabelText('Sign in using'), { target: { value: 'ldap' } }); + await submit('é'.repeat(513), 'é'.repeat(2049)); + expect(authManager.login).not.toHaveBeenCalled(); + expect(screen.getByText('Username must be at most 1024 bytes')).toBeTruthy(); + expect(screen.getByText('Password must be at most 4096 bytes')).toBeTruthy(); + }); +}); diff --git a/frontend/src/pages/RoleManagementPage.svelte b/frontend/src/pages/RoleManagementPage.svelte index 290b0d06..657e56e2 100644 --- a/frontend/src/pages/RoleManagementPage.svelte +++ b/frontend/src/pages/RoleManagementPage.svelte @@ -4,6 +4,8 @@ import { showError, showSuccess } from '../lib/toast.svelte'; import { authManager } from '../lib/auth.svelte'; import { router } from '../lib/router.svelte'; + import LdapAdministration from '../components/LdapAdministration.svelte'; + import { authProviders } from '../lib/authProviders.svelte'; import LoadingSpinner from '../components/LoadingSpinner.svelte'; import RoleDetailDialog from '../components/RoleDetailDialog.svelte'; import CreateRoleDialog from '../components/CreateRoleDialog.svelte'; @@ -60,6 +62,7 @@ return; } + void authProviders.discover(); // Load initial data loadRoles(); }); @@ -167,6 +170,10 @@

+ {#if authManager.isAdmin && authManager.hasPermission('rbac', 'admin') && authProviders.ldap?.enabled && !isRoleDialogOpen} + + {/if} +
diff --git a/frontend/src/pages/UserManagementPage.svelte b/frontend/src/pages/UserManagementPage.svelte index 82787085..078e6476 100644 --- a/frontend/src/pages/UserManagementPage.svelte +++ b/frontend/src/pages/UserManagementPage.svelte @@ -1,4 +1,5 @@