Release v0.1.15

.gitea/workflows/module-package-release.yml

@@ -0,0 +1,270 @@
+name: Module Package Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Existing protected version tag to publish
+        required: true
+        type: string
+
+jobs:
+  publish-packages:
+    runs-on: ubuntu-latest
+    env:
+      GITEA_REPOSITORY: ${{ gitea.repository }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "22"
+      - name: Select and validate protected release tag
+        shell: bash
+        env:
+          REQUESTED_TAG: ${{ inputs.release_tag }}
+          TRIGGER_TAG: ${{ gitea.ref_name }}
+        run: |
+          set -euo pipefail
+          tag="${REQUESTED_TAG:-$TRIGGER_TAG}"
+          case "$tag" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *) echo "Release tag must start with a SemVer-shaped vX.Y.Z value" >&2; exit 1 ;;
+          esac
+          git fetch --force origin "refs/tags/$tag:refs/tags/$tag" refs/heads/main:refs/remotes/origin/main
+          tag_commit="$(git rev-list -n 1 "$tag")"
+          git merge-base --is-ancestor "$tag_commit" refs/remotes/origin/main || {
+            echo "Release tag is not contained in main" >&2
+            exit 1
+          }
+          git checkout --detach "$tag"
+          printf 'RELEASE_TAG=%s\n' "$tag" >> "$GITEA_ENV"
+          printf 'SOURCE_DATE_EPOCH=%s\n' "$(git show -s --format=%ct HEAD)" >> "$GITEA_ENV"
+      - name: Validate package versions
+        run: |
+          python - <<'PY'
+          import json
+          from pathlib import Path
+          import os
+          import re
+          import tomllib
+
+          tag = os.environ["RELEASE_TAG"]
+          expected = tag.removeprefix("v")
+          project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]
+          if project.get("version") != expected:
+              raise SystemExit(f"pyproject version {project.get('version')!r} does not match {tag}")
+          if re.fullmatch(r"govoplan-[a-z0-9-]+", str(project.get("name", ""))) is None:
+              raise SystemExit("Python distribution name must use the govoplan-* namespace")
+          webui = Path("webui/package.json")
+          if webui.is_file():
+              package = json.loads(webui.read_text(encoding="utf-8"))
+              if package.get("version") != expected:
+                  raise SystemExit(f"WebUI version {package.get('version')!r} does not match {tag}")
+              if re.fullmatch(r"@govoplan/[a-z0-9-]+-webui", str(package.get("name", ""))) is None:
+                  raise SystemExit("WebUI package name must use the @govoplan/*-webui namespace")
+              release = Path("webui/package.release.json")
+              if release.is_file():
+                  release_package = json.loads(release.read_text(encoding="utf-8"))
+                  if (
+                      release_package.get("name") != package.get("name")
+                      or release_package.get("version") != expected
+                  ):
+                      raise SystemExit("WebUI release package identity does not match package.json and the release tag")
+          PY
+      - name: Build immutable package artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m pip install --disable-pip-version-check build==1.5.0 twine==7.0.0
+          rm -rf dist .package-webui
+          python -m build --wheel --outdir dist
+          python -m twine check dist/*.whl
+          if [[ -f webui/package.json ]]; then
+            mkdir .package-webui
+            cp -a webui/. .package-webui/
+            rm -rf .package-webui/node_modules .package-webui/dist
+            if [[ -f .package-webui/package.release.json ]]; then
+              cp .package-webui/package.release.json .package-webui/package.json
+            fi
+          node <<'NODE'
+          const fs = require("node:fs");
+          const path = ".package-webui/package.json";
+          const packageJson = JSON.parse(fs.readFileSync(path, "utf8"));
+          const groups = ["dependencies", "optionalDependencies", "peerDependencies"];
+          for (const group of groups) {
+            for (const [name, specifier] of Object.entries(packageJson[group] || {})) {
+              if (!name.startsWith("@govoplan/")) continue;
+              if (typeof specifier !== "string") {
+                throw new Error(`${group}.${name} must use a string version`);
+              }
+              const packageSlug = name.slice("@govoplan/".length);
+              if (!packageSlug.endsWith("-webui")) {
+                throw new Error(`${group}.${name} is outside the WebUI package namespace`);
+              }
+              const repository = `govoplan-${packageSlug.slice(0, -"-webui".length)}`;
+              const escapedRepository = repository.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+              const gitTag = specifier.match(
+                new RegExp(
+                  `^git\\+(?:ssh://git@|https://)git\\.add-ideas\\.de/(?:GovOPlaN|add-ideas)/${escapedRepository}\\.git#v([0-9]+\\.[0-9]+\\.[0-9]+)$`,
+                ),
+              );
+              if (gitTag) {
+                packageJson[group][name] = gitTag[1];
+                continue;
+              }
+              if (specifier.startsWith("file:") || specifier.startsWith("git+")) {
+                throw new Error(
+                  `${group}.${name} must resolve to an exact registry version for publication`,
+                );
+              }
+            }
+          }
+          delete packageJson.private;
+          fs.writeFileSync(path, `${JSON.stringify(packageJson, null, 2)}\n`);
+          NODE
+            npm pkg delete private --prefix .package-webui
+            (cd .package-webui && npm pack --ignore-scripts --pack-destination ../dist)
+          fi
+          python - <<'PY'
+          import hashlib
+          import json
+          from pathlib import Path
+          import os
+          import subprocess
+
+          artifacts = []
+          for path in sorted(Path("dist").iterdir()):
+              if path.suffix not in {".whl", ".tgz"}:
+                  continue
+              digest = hashlib.sha256(path.read_bytes()).hexdigest()
+              artifacts.append({"filename": path.name, "sha256": digest, "size": path.stat().st_size})
+          payload = {
+              "schema_version": "1",
+              "repository": os.environ["GITEA_REPOSITORY"],
+              "tag": os.environ["RELEASE_TAG"],
+              "commit": subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip(),
+              "artifacts": artifacts,
+          }
+          Path("dist/package-artifacts.json").write_text(
+              json.dumps(payload, indent=2, sort_keys=True) + "\n",
+              encoding="utf-8",
+          )
+          PY
+      - name: Retain package hash evidence
+        uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32
+        with:
+          name: module-packages-${{ gitea.ref_name }}
+          path: dist/package-artifacts.json
+      - name: Check immutable registry state
+        shell: bash
+        env:
+          PACKAGE_TOKEN: ${{ secrets.GOVOPLAN_PACKAGE_TOKEN }}
+        run: |
+          set -euo pipefail
+          test -n "$PACKAGE_TOKEN"
+          python - <<'PY'
+          import hashlib
+          import json
+          import os
+          from pathlib import Path
+          import tomllib
+          from urllib.error import HTTPError
+          from urllib.parse import quote
+          from urllib.request import Request, urlopen
+
+          api_root = "https://git.add-ideas.de/api/v1/packages/GovOPlaN"
+          token = os.environ["PACKAGE_TOKEN"]
+
+          def should_publish(kind, name, version, path):
+              package_url = "/".join(
+                  (api_root, kind, quote(name, safe=""), quote(version, safe=""), "files")
+              )
+              request = Request(
+                  package_url,
+                  headers={"Accept": "application/json", "Authorization": f"token {token}"},
+              )
+              try:
+                  with urlopen(request, timeout=30) as response:
+                      files = json.load(response)
+              except HTTPError as exc:
+                  if exc.code == 404:
+                      print(f"{kind} package {name}=={version} is not published yet")
+                      return True
+                  raise
+              if not isinstance(files, list) or len(files) != 1:
+                  raise SystemExit(
+                      f"immutable {kind} package {name}=={version} has an unexpected file set"
+                  )
+              expected_sha256 = hashlib.sha256(path.read_bytes()).hexdigest()
+              if files[0].get("sha256") != expected_sha256:
+                  raise SystemExit(
+                      f"immutable {kind} package {name}=={version} already exists with a different SHA-256"
+                  )
+              print(f"verified existing {kind} package {name}=={version} ({expected_sha256})")
+              return False
+
+          project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]
+          wheels = tuple(Path("dist").glob("*.whl"))
+          if len(wheels) != 1:
+              raise SystemExit("release build must contain exactly one wheel")
+          publish_pypi = should_publish(
+              "pypi", str(project["name"]), str(project["version"]), wheels[0]
+          )
+
+          tarballs = tuple(Path("dist").glob("*.tgz"))
+          if len(tarballs) > 1:
+              raise SystemExit("release build must contain at most one npm package")
+          publish_npm = False
+          if tarballs:
+              webui = json.loads(
+                  Path(".package-webui/package.json").read_text(encoding="utf-8")
+              )
+              publish_npm = should_publish(
+                  "npm", str(webui["name"]), str(webui["version"]), tarballs[0]
+              )
+
+          with Path(os.environ["GITEA_ENV"]).open("a", encoding="utf-8") as env_file:
+              env_file.write(f"PUBLISH_PYPI={int(publish_pypi)}\n")
+              env_file.write(f"PUBLISH_NPM={int(publish_npm)}\n")
+          PY
+      - name: Publish wheel and WebUI package
+        shell: bash
+        env:
+          PACKAGE_USERNAME: ${{ secrets.GOVOPLAN_PACKAGE_USERNAME }}
+          PACKAGE_TOKEN: ${{ secrets.GOVOPLAN_PACKAGE_TOKEN }}
+        run: |
+          set -euo pipefail
+          test -n "$PACKAGE_USERNAME"
+          test -n "$PACKAGE_TOKEN"
+          if [[ "$PUBLISH_PYPI" == 1 ]]; then
+            TWINE_USERNAME="$PACKAGE_USERNAME" TWINE_PASSWORD="$PACKAGE_TOKEN" \
+              python -m twine upload --non-interactive \
+                --repository-url https://git.add-ideas.de/api/packages/GovOPlaN/pypi \
+                dist/*.whl
+          else
+            echo "Exact wheel is already present; skipping immutable retry."
+          fi
+          shopt -s nullglob
+          webui_packages=(dist/*.tgz)
+          if (( ${#webui_packages[@]} )) && [[ "$PUBLISH_NPM" == 1 ]]; then
+            npmrc="$(mktemp)"
+            trap 'rm -f "$npmrc"' EXIT
+            chmod 600 "$npmrc"
+            printf '%s\n' \
+              '@govoplan:registry=https://git.add-ideas.de/api/packages/GovOPlaN/npm/' \
+              "//git.add-ideas.de/api/packages/GovOPlaN/npm/:_authToken=$PACKAGE_TOKEN" \
+              > "$npmrc"
+            NPM_CONFIG_USERCONFIG="$npmrc" npm publish "./${webui_packages[0]}" \
+              --ignore-scripts --access public \
+              --registry https://git.add-ideas.de/api/packages/GovOPlaN/npm/
+          elif (( ${#webui_packages[@]} )); then
+            echo "Exact WebUI package is already present; skipping immutable retry."
+          fi

.gitignore

@@ -6,3 +6,270 @@ __pycache__/
 .ruff_cache/
 build/
 dist/
+
+# GovOPlaN shared ignore rules from govoplan-core
+# ---> Node
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+# nyc test coverage
+.nyc_output
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+# Bower dependency directory (https://bower.io/)
+bower_components
+# node-waf configuration
+.lock-wscript
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+# Dependency directories
+node_modules/
+jspm_packages/
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+# TypeScript cache
+*.tsbuildinfo
+# Optional npm cache directory
+.npm
+# Optional eslint cache
+.eslintcache
+# Optional stylelint cache
+.stylelintcache
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+# Optional REPL history
+.node_repl_history
+# Output of 'npm pack'
+*.tgz
+# Yarn Integrity file
+.yarn-integrity
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+# Next.js build output
+.next
+out
+# Nuxt.js build / generate output
+.nuxt
+dist
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+# vuepress build output
+.vuepress/dist
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+# vitepress build output
+**/.vitepress/dist
+# vitepress cache directory
+**/.vitepress/cache
+# Docusaurus cache and generated files
+.docusaurus
+# Serverless directories
+.serverless/
+# FuseBox cache
+.fusebox/
+# DynamoDB Local files
+.dynamodb/
+# TernJS port file
+.tern-port
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+# Local WebUI test/build scratch directories
+.component-test-build/
+.module-test-build/
+.policy-test-build/
+.template-preview-test-build/
+.import-test-build/
+webui/.component-test-build/
+webui/.module-test-build/
+webui/.policy-test-build/
+webui/.template-preview-test-build/
+webui/.import-test-build/
+# ---> Python
+# Byte-compiled / optimized / DLL files
+*$py.class
+# C extensions
+*.so
+# Distribution / packaging
+.Python
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+.installed.cfg
+*.egg
+MANIFEST
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+cover/
+# Translations
+*.mo
+*.pot
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+# Flask stuff:
+instance/
+.webassets-cache
+# Scrapy stuff:
+.scrapy
+# Sphinx documentation
+docs/_build/
+# PyBuilder
+.pybuilder/
+target/
+# Jupyter Notebook
+.ipynb_checkpoints
+# IPython
+profile_default/
+ipython_config.py
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+# SageMath parsed files
+*.sage.py
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+# Spyder project settings
+.spyderproject
+.spyproject
+# Rope project settings
+.ropeproject
+# mkdocs documentation
+/site
+# mypy
+.dmypy.json
+dmypy.json
+# Pyre type checker
+.pyre/
+# pytype static type analyzer
+.pytype/
+# Cython debug symbols
+cython_debug/
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+# Ruff stuff:
+# PyPI configuration file
+.pypirc
+# ---> VisualStudioCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+# Local History for Visual Studio Code
+.history/
+# Built Visual Studio Code Extensions
+*.vsix
+*.db
+# GovOPlaN local runtime state
+runtime/
+# GovOPlaN WebUI test output
+webui/.module-test-build/
+webui/.component-test-build/

AGENTS.md

@@ -1,5 +1,11 @@
 # GovOPlaN Identity Codex Guide
 
+## Documentation Contract
+
+- Treat documentation as part of every behavior change. Update this module's manifest-driven `DocumentationTopic` contributions for affected user and administrator behavior.
+- Keep feature content here; `govoplan-docs` projects it without importing Identity internals.
+- Maintain a static user/admin baseline and run `/mnt/DATA/git/govoplan/tools/checks/check-manifest-shapes.py` after behavior or manifest changes.
+
 ## Scope
 
 This repository owns the canonical GovOPlaN identity directory: internal

README.md

@@ -1,5 +1,9 @@
 # GovOPlaN Identity
 
+<!-- govoplan-repository-type:start -->
+**Repository type:** module (platform).
+<!-- govoplan-repository-type:end -->
+
 `govoplan-identity` is the canonical identity directory module for GovOPlaN.
 
 It owns identities and links between identities and platform accounts. This is

docs/IDENTITY_MODEL.md

@@ -17,11 +17,34 @@ an account. Access can then evaluate roles, rights, delegation, and policy.
 
 ## Boundary With Organizations
 
-Organization functions and function assignments live in
+Organization functions live in `govoplan-organizations`.
-`govoplan-organizations`. Those assignments may reference identity and account
+Identity-to-function assignments live in `govoplan-idm`. Those assignments may
-IDs, but identity does not own organizational structure.
+reference identity and account IDs, but identity does not own organizational
+structure or assignment workflows.
 
 ## Boundary With IDM
 
 `govoplan-idm` imports, previews, reconciles, and applies external identity
 facts. Once accepted, normalized identity records belong here.
+
+## Access Projection Migration
+
+`govoplan-access` now prefers `identity.directory` when it needs to resolve the
+identity behind an account or render identity labels in semantic access views.
+If the identity module is not installed, Access falls back to the legacy
+`access_identities` and `access_identity_account_links` projection tables.
+
+Rollout plan:
+
+- keep the Access projection tables readable until existing installations have
+  a backfill path;
+- backfill `identity_identities` and `identity_account_links` from the Access
+  projection where Identity is newly installed on an existing deployment;
+- keep Access writes that still create local accounts able to maintain the
+  projection during the compatibility window;
+- once deployments use `identity.directory` consistently, retire direct Access
+  identity reads and leave the projection tables as migration-only data until a
+  release-level retirement plan removes them.
+
+The close-out condition is that Access works with canonical Identity installed
+and still works without it through the projection fallback.

pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-identity"
-version = "0.1.6"
+version = "0.1.15"
 description = "GovOPlaN identity directory module."
 readme = "README.md"
 requires-python = ">=3.12"
 authors = [{ name = "GovOPlaN" }]
 dependencies = [
-  "govoplan-core>=0.1.6",
+  "govoplan-core>=0.1.15",
 ]
 
 [tool.setuptools.packages.find]

src/govoplan_identity/__init__.py

@@ -1,3 +1,3 @@
 """GovOPlaN identity module."""
 
-__version__ = "0.1.6"
+__version__ = "0.1.15"

src/govoplan_identity/backend/api/__init__.py

@@ -0,0 +1 @@
+"""Identity API package."""

src/govoplan_identity/backend/api/v1/__init__.py

@@ -0,0 +1 @@
+"""Identity API v1 package."""

src/govoplan_identity/backend/api/v1/routes.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import func, or_
+from sqlalchemy.orm import Session
+
+from govoplan_core.auth import ApiPrincipal, require_any_scope
+from govoplan_core.db.session import get_session
+from govoplan_identity.backend.db.models import Identity, IdentityAccountLink
+
+from .schemas import IdentityItem, IdentityListResponse
+
+
+router = APIRouter(prefix="/identity", tags=["identity"])
+
+IDENTITY_READ_SCOPES = (
+    "identity:identity:read",
+    "identity:read",
+    "admin:users:read",
+    "system:accounts:read",
+    "organizations:function:assign",
+)
+
+
+@router.get("/identities", response_model=IdentityListResponse)
+def list_identities(
+    query: str | None = Query(default=None, min_length=1, max_length=255),
+    limit: int = Query(default=25, ge=1, le=100),
+    include_inactive: bool = False,
+    session: Session = Depends(get_session),
+    principal: ApiPrincipal = Depends(require_any_scope(*IDENTITY_READ_SCOPES)),
+) -> IdentityListResponse:
+    del principal
+    identity_query = session.query(Identity)
+    if not include_inactive:
+        identity_query = identity_query.filter(Identity.is_active.is_(True))
+    if query:
+        pattern = f"%{query.strip().casefold()}%"
+        matching_account_links = session.query(IdentityAccountLink.identity_id).filter(
+            func.lower(IdentityAccountLink.account_id).like(pattern)
+        )
+        identity_query = identity_query.filter(
+            or_(
+                func.lower(Identity.id).like(pattern),
+                func.lower(Identity.display_name).like(pattern),
+                func.lower(Identity.external_subject).like(pattern),
+                Identity.id.in_(matching_account_links),
+            )
+        )
+
+    identities = identity_query.order_by(Identity.display_name.asc(), Identity.id.asc()).limit(limit).all()
+    identity_ids = [identity.id for identity in identities]
+    links_by_identity: dict[str, list[IdentityAccountLink]] = {identity_id: [] for identity_id in identity_ids}
+    if identity_ids:
+        links = (
+            session.query(IdentityAccountLink)
+            .filter(IdentityAccountLink.identity_id.in_(identity_ids))
+            .order_by(IdentityAccountLink.is_primary.desc(), IdentityAccountLink.account_id.asc())
+            .all()
+        )
+        for link in links:
+            links_by_identity.setdefault(link.identity_id, []).append(link)
+
+    return IdentityListResponse(
+        identities=[
+            _identity_item(identity, links_by_identity.get(identity.id, []))
+            for identity in identities
+        ]
+    )
+
+
+def _identity_item(identity: Identity, links: list[IdentityAccountLink]) -> IdentityItem:
+    primary_link = next((link for link in links if link.is_primary), None)
+    return IdentityItem(
+        id=identity.id,
+        display_name=identity.display_name,
+        external_subject=identity.external_subject,
+        source=identity.source,
+        primary_account_id=primary_link.account_id if primary_link is not None else None,
+        account_ids=[link.account_id for link in links],
+        status="active" if identity.is_active else "inactive",
+    )

src/govoplan_identity/backend/api/v1/schemas.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class IdentityItem(BaseModel):
+    id: str
+    display_name: str | None = None
+    external_subject: str | None = None
+    source: str
+    primary_account_id: str | None = None
+    account_ids: list[str]
+    status: str
+
+
+class IdentityListResponse(BaseModel):
+    identities: list[IdentityItem]

src/govoplan_identity/backend/directory.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from collections.abc import Sequence
 
+from sqlalchemy import func, or_
+
 from govoplan_core.core.identity import IdentityAccountLinkRef, IdentityDirectory, IdentityRef
 from govoplan_core.db.session import get_database
 from govoplan_identity.backend.db.models import Identity, IdentityAccountLink
@@ -103,3 +105,49 @@ class SqlIdentityDirectory(IdentityDirectory):
                 .all()
             )
             return tuple(_link_ref(link) for link in links)
+
+    def search_identities(
+        self,
+        query: str | None = None,
+        *,
+        include_inactive: bool = False,
+        limit: int = 25,
+    ) -> tuple[IdentityRef, ...]:
+        normalized_limit = max(1, min(int(limit), 100))
+        with get_database().session() as session:
+            identity_query = session.query(Identity)
+            if not include_inactive:
+                identity_query = identity_query.filter(Identity.is_active.is_(True))
+            if query and query.strip():
+                pattern = f"%{query.strip().casefold()}%"
+                matching_account_links = session.query(IdentityAccountLink.identity_id).filter(
+                    func.lower(IdentityAccountLink.account_id).like(pattern)
+                )
+                identity_query = identity_query.filter(
+                    or_(
+                        func.lower(Identity.id).like(pattern),
+                        func.lower(Identity.display_name).like(pattern),
+                        func.lower(Identity.external_subject).like(pattern),
+                        Identity.id.in_(matching_account_links),
+                    )
+                )
+
+            identities = (
+                identity_query
+                .order_by(Identity.display_name.asc(), Identity.id.asc())
+                .limit(normalized_limit)
+                .all()
+            )
+            identity_ids = [identity.id for identity in identities]
+            links = (
+                session.query(IdentityAccountLink)
+                .filter(IdentityAccountLink.identity_id.in_(identity_ids))
+                .order_by(IdentityAccountLink.is_primary.desc(), IdentityAccountLink.account_id.asc())
+                .all()
+                if identity_ids
+                else []
+            )
+            links_by_identity: dict[str, list[IdentityAccountLink]] = {}
+            for link in links:
+                links_by_identity.setdefault(link.identity_id, []).append(link)
+            return tuple(_identity_ref(identity, links_by_identity.get(identity.id, ())) for identity in identities)

src/govoplan_identity/backend/manifest.py

@@ -1,12 +1,51 @@
 from __future__ import annotations
 
-from govoplan_core.core.identity import CAPABILITY_IDENTITY_DIRECTORY
+from pathlib import Path
+
+from govoplan_core.core.access import CAPABILITY_AUTH_PERMISSION_EVALUATOR, CAPABILITY_AUTH_PRINCIPAL_RESOLVER
+from govoplan_core.core.identity import CAPABILITY_IDENTITY_DIRECTORY, CAPABILITY_IDENTITY_SEARCH
 from govoplan_core.core.module_guards import persistent_table_uninstall_guard
-from govoplan_core.core.modules import DocumentationTopic, MigrationSpec, ModuleContext, ModuleManifest
+from govoplan_core.core.modules import DocumentationTopic, MigrationSpec, ModuleContext, ModuleManifest, PermissionDefinition, RoleTemplate
+from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.db.base import Base
 from govoplan_identity.backend.db import models as identity_models  # noqa: F401 - populate metadata
 
 
+def _permission(scope: str, label: str, description: str) -> PermissionDefinition:
+    module_id, resource, action = scope.split(":", 2)
+    return PermissionDefinition(
+        scope=scope,
+        label=label,
+        description=description,
+        category="Identity",
+        level="tenant",
+        module_id=module_id,
+        resource=resource,
+        action=action,
+    )
+
+
+PERMISSIONS = (
+    _permission("identity:identity:read", "View identities", "Search and read normalized identities and their account links."),
+)
+
+ROLE_TEMPLATES = (
+    RoleTemplate(
+        slug="identity_viewer",
+        name="Identity viewer",
+        description="Read normalized identities and account links.",
+        permissions=("identity:identity:read",),
+    ),
+)
+
+
+def _route_factory(context: ModuleContext):
+    del context
+    from govoplan_identity.backend.api.v1.routes import router
+
+    return router
+
+
 def _identity_directory(context: ModuleContext) -> object:
     del context
     from govoplan_identity.backend.directory import SqlIdentityDirectory
@@ -17,8 +56,17 @@ def _identity_directory(context: ModuleContext) -> object:
 manifest = ModuleManifest(
     id="identity",
     name="Identity",
-    version="0.1.6",
+    version="0.1.15",
-    migration_spec=MigrationSpec(module_id="identity", metadata=Base.metadata),
+    required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
+    permissions=PERMISSIONS,
+    role_templates=ROLE_TEMPLATES,
+    route_factory=_route_factory,
+    migration_spec=MigrationSpec(
+        module_id="identity",
+        metadata=Base.metadata,
+        script_location=str(Path(__file__).with_name("migrations") / "versions"),
+        migration_after=("access",),
+    ),
     uninstall_guard_providers=(
         persistent_table_uninstall_guard(
             identity_models.Identity,
@@ -28,6 +76,7 @@ manifest = ModuleManifest(
     ),
     capability_factories={
         CAPABILITY_IDENTITY_DIRECTORY: _identity_directory,
+        CAPABILITY_IDENTITY_SEARCH: _identity_directory,
     },
     documentation=(
         DocumentationTopic(
@@ -44,6 +93,17 @@ manifest = ModuleManifest(
             order=24,
         ),
     ),
+    architecture=declared_module_architecture(
+        layer="institutional_foundation",
+        kind="foundation",
+        maturity="vertical_slice",
+        documentation_ref="docs/IDENTITY_MODEL.md",
+        test_ref="tests/test_directory.py",
+        known_limits=("Identity proofing and external-directory reconciliation are outside the current vertical slice.",),
+        owned_concepts=("identity", "identity-account link"),
+        non_owned_concepts=("account authentication", "function assignment", "contact point", "organization"),
+        security_docs=("docs/IDENTITY_MODEL.md",),
+    ),
 )
 
 

src/govoplan_identity/backend/migrations/__init__.py

@@ -0,0 +1 @@
+"""Identity module migrations."""

src/govoplan_identity/backend/migrations/dev_versions/5c6d7e8f9a10_identity_directory.py

@@ -0,0 +1,141 @@
+"""identity directory
+
+Revision ID: 5c6d7e8f9a10
+Revises: 4a5b6c7d8e9f
+Create Date: 2026-07-11 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "5c6d7e8f9a10"
+down_revision = "4a5b6c7d8e9f"
+branch_labels = None
+depends_on = None
+
+
+def _tables() -> set[str]:
+    return set(sa.inspect(op.get_bind()).get_table_names())
+
+
+def _indexes(table_name: str) -> set[str]:
+    if table_name not in _tables():
+        return set()
+    return {item["name"] for item in sa.inspect(op.get_bind()).get_indexes(table_name)}
+
+
+def _create_index_if_missing(name: str, table_name: str, columns: list[str], *, unique: bool = False, **kwargs) -> None:
+    if table_name in _tables() and name not in _indexes(table_name):
+        op.create_index(name, table_name, columns, unique=unique, **kwargs)
+
+
+def _drop_index_if_exists(name: str, table_name: str) -> None:
+    if table_name in _tables() and name in _indexes(table_name):
+        op.drop_index(name, table_name=table_name)
+
+
+def upgrade() -> None:
+    tables = _tables()
+    if "identity_identities" not in tables:
+        op.create_table(
+            "identity_identities",
+            sa.Column("id", sa.String(length=36), nullable=False),
+            sa.Column("display_name", sa.String(length=255), nullable=True),
+            sa.Column("external_subject", sa.String(length=255), nullable=True),
+            sa.Column("source", sa.String(length=50), nullable=False),
+            sa.Column("is_active", sa.Boolean(), nullable=False),
+            sa.Column("settings", sa.JSON(), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+            sa.PrimaryKeyConstraint("id", name=op.f("pk_identity_identities")),
+        )
+    _create_index_if_missing(op.f("ix_identity_identities_external_subject"), "identity_identities", ["external_subject"])
+
+    tables = _tables()
+    if "identity_account_links" not in tables:
+        op.create_table(
+            "identity_account_links",
+            sa.Column("id", sa.String(length=36), nullable=False),
+            sa.Column("identity_id", sa.String(length=36), nullable=False),
+            sa.Column("account_id", sa.String(length=36), nullable=False),
+            sa.Column("is_primary", sa.Boolean(), nullable=False),
+            sa.Column("source", sa.String(length=50), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+            sa.ForeignKeyConstraint(
+                ["identity_id"],
+                ["identity_identities.id"],
+                name=op.f("fk_identity_account_links_identity_id_identity_identities"),
+                ondelete="CASCADE",
+            ),
+            sa.PrimaryKeyConstraint("id", name=op.f("pk_identity_account_links")),
+            sa.UniqueConstraint("identity_id", "account_id", name="uq_identity_module_account_links_identity_account"),
+        )
+    _create_index_if_missing(op.f("ix_identity_account_links_account_id"), "identity_account_links", ["account_id"])
+    _create_index_if_missing(op.f("ix_identity_account_links_identity_id"), "identity_account_links", ["identity_id"])
+    _create_index_if_missing(
+        "uq_identity_module_account_links_primary_account",
+        "identity_account_links",
+        ["account_id"],
+        unique=True,
+        sqlite_where=sa.text("is_primary = 1"),
+        postgresql_where=sa.text("is_primary IS TRUE"),
+    )
+    _create_index_if_missing(
+        "uq_identity_module_account_links_primary_identity",
+        "identity_account_links",
+        ["identity_id"],
+        unique=True,
+        sqlite_where=sa.text("is_primary = 1"),
+        postgresql_where=sa.text("is_primary IS TRUE"),
+    )
+
+    tables = _tables()
+    if {"access_identities", "access_identity_account_links"}.issubset(tables):
+        op.execute("""
+            INSERT INTO identity_identities
+                (id, display_name, external_subject, source, is_active, settings, created_at, updated_at)
+            SELECT id, display_name, external_subject, source, is_active, settings, created_at, updated_at
+            FROM access_identities source_identity
+            WHERE NOT EXISTS (
+                SELECT 1
+                FROM identity_identities target_identity
+                WHERE target_identity.id = source_identity.id
+            )
+        """)
+        op.execute("""
+            INSERT INTO identity_account_links
+                (id, identity_id, account_id, is_primary, source, created_at, updated_at)
+            SELECT id, identity_id, account_id, is_primary, source, created_at, updated_at
+            FROM access_identity_account_links source_link
+            WHERE EXISTS (
+                SELECT 1
+                FROM identity_identities target_identity
+                WHERE target_identity.id = source_link.identity_id
+            )
+              AND NOT EXISTS (
+                SELECT 1
+                FROM identity_account_links target_link
+                WHERE target_link.id = source_link.id
+            )
+              AND NOT EXISTS (
+                SELECT 1
+                FROM identity_account_links target_link
+                WHERE target_link.identity_id = source_link.identity_id
+                  AND target_link.account_id = source_link.account_id
+            )
+        """)
+
+
+def downgrade() -> None:
+    _drop_index_if_exists("uq_identity_module_account_links_primary_identity", "identity_account_links")
+    _drop_index_if_exists("uq_identity_module_account_links_primary_account", "identity_account_links")
+    _drop_index_if_exists(op.f("ix_identity_account_links_identity_id"), "identity_account_links")
+    _drop_index_if_exists(op.f("ix_identity_account_links_account_id"), "identity_account_links")
+    if "identity_account_links" in _tables():
+        op.drop_table("identity_account_links")
+    _drop_index_if_exists(op.f("ix_identity_identities_external_subject"), "identity_identities")
+    if "identity_identities" in _tables():
+        op.drop_table("identity_identities")

src/govoplan_identity/backend/migrations/dev_versions/__init__.py

@@ -0,0 +1 @@
+"""Identity module migration versions."""

src/govoplan_identity/backend/migrations/versions/5c6d7e8f9a10_v017_identity_baseline.py

@@ -0,0 +1,52 @@
+"""v0.1.7 identity baseline
+
+Revision ID: 5c6d7e8f9a10
+Revises: None
+Create Date: 2026-07-11 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = '5c6d7e8f9a10'
+down_revision = None
+branch_labels = None
+depends_on = ('4f2a9c8e7b6d', '4a5b6c7d8e9f')
+
+
+def upgrade() -> None:
+    op.create_table('identity_identities',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('display_name', sa.String(length=255), nullable=True),
+    sa.Column('external_subject', sa.String(length=255), nullable=True),
+    sa.Column('source', sa.String(length=50), nullable=False),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('settings', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_identity_identities'))
+    )
+    op.create_index(op.f('ix_identity_identities_external_subject'), 'identity_identities', ['external_subject'], unique=False)
+    op.create_table('identity_account_links',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('identity_id', sa.String(length=36), nullable=False),
+    sa.Column('account_id', sa.String(length=36), nullable=False),
+    sa.Column('is_primary', sa.Boolean(), nullable=False),
+    sa.Column('source', sa.String(length=50), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['identity_id'], ['identity_identities.id'], name=op.f('fk_identity_account_links_identity_id_identity_identities'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_identity_account_links')),
+    sa.UniqueConstraint('identity_id', 'account_id', name='uq_identity_module_account_links_identity_account')
+    )
+    op.create_index(op.f('ix_identity_account_links_account_id'), 'identity_account_links', ['account_id'], unique=False)
+    op.create_index(op.f('ix_identity_account_links_identity_id'), 'identity_account_links', ['identity_id'], unique=False)
+    op.create_index('uq_identity_module_account_links_primary_account', 'identity_account_links', ['account_id'], unique=True, sqlite_where=sa.text('is_primary = 1'), postgresql_where=sa.text('is_primary IS TRUE'))
+    op.create_index('uq_identity_module_account_links_primary_identity', 'identity_account_links', ['identity_id'], unique=True, sqlite_where=sa.text('is_primary = 1'), postgresql_where=sa.text('is_primary IS TRUE'))
+
+
+def downgrade() -> None:
+    op.drop_table('identity_account_links')
+    op.drop_table('identity_identities')

src/govoplan_identity/backend/migrations/versions/__init__.py

@@ -0,0 +1 @@
+"""Identity module migration versions."""

tests/test_directory.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import unittest
+
+from govoplan_core.core.identity import IdentitySearchProvider
+from govoplan_core.db.base import Base
+from govoplan_core.db.session import configure_database, reset_database
+from govoplan_identity.backend.db.models import Identity, IdentityAccountLink
+from govoplan_identity.backend.directory import SqlIdentityDirectory
+
+
+class IdentityDirectoryTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.database = configure_database("sqlite:///:memory:")
+        Base.metadata.create_all(
+            self.database.engine,
+            tables=[Identity.__table__, IdentityAccountLink.__table__],
+        )
+        with self.database.session() as session:
+            active = Identity(
+                id="identity-active",
+                display_name="Ada Example",
+                external_subject="subject-active",
+                source="local",
+                is_active=True,
+                settings={},
+            )
+            inactive = Identity(
+                id="identity-inactive",
+                display_name="Inactive Person",
+                external_subject="subject-inactive",
+                source="local",
+                is_active=False,
+                settings={},
+            )
+            session.add_all([active, inactive])
+            session.flush()
+            session.add_all(
+                [
+                    IdentityAccountLink(
+                        id="link-active",
+                        identity_id=active.id,
+                        account_id="account-ada",
+                        is_primary=True,
+                        source="local",
+                    ),
+                    IdentityAccountLink(
+                        id="link-inactive",
+                        identity_id=inactive.id,
+                        account_id="account-inactive",
+                        is_primary=True,
+                        source="local",
+                    ),
+                ]
+            )
+            session.commit()
+
+    def tearDown(self) -> None:
+        reset_database(dispose=True)
+
+    def test_search_capability_filters_inactive_identities_and_searches_account_ids(self) -> None:
+        directory = SqlIdentityDirectory()
+
+        self.assertIsInstance(directory, IdentitySearchProvider)
+        self.assertEqual(
+            ("identity-active",),
+            tuple(identity.id for identity in directory.search_identities()),
+        )
+        matches = directory.search_identities("account-ada")
+        self.assertEqual(("identity-active",), tuple(identity.id for identity in matches))
+        self.assertEqual(("account-ada",), matches[0].account_ids)
+        self.assertEqual("account-ada", matches[0].primary_account_id)
+
+    def test_search_capability_can_include_inactive_identities(self) -> None:
+        directory = SqlIdentityDirectory()
+
+        matches = directory.search_identities("inactive", include_inactive=True)
+
+        self.assertEqual(("identity-inactive",), tuple(identity.id for identity in matches))
+
+
+if __name__ == "__main__":
+    unittest.main()