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

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

pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-identity"
-version = "0.1.7"
+version = "0.1.15"
 description = "GovOPlaN identity directory module."
 readme = "README.md"
 requires-python = ">=3.12"
 authors = [{ name = "GovOPlaN" }]
 dependencies = [
-  "govoplan-core>=0.1.7",
+  "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/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

@@ -3,9 +3,10 @@ from __future__ import annotations
 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
+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, 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
 
@@ -55,7 +56,7 @@ def _identity_directory(context: ModuleContext) -> object:
 manifest = ModuleManifest(
     id="identity",
     name="Identity",
-    version="0.1.7",
+    version="0.1.15",
     required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
     permissions=PERMISSIONS,
     role_templates=ROLE_TEMPLATES,
@@ -75,6 +76,7 @@ manifest = ModuleManifest(
     ),
     capability_factories={
         CAPABILITY_IDENTITY_DIRECTORY: _identity_directory,
+        CAPABILITY_IDENTITY_SEARCH: _identity_directory,
     },
     documentation=(
         DocumentationTopic(
@@ -91,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/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')

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()