feat(access): document consequential credential controls

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govoplan/access-webui",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "private": true,
   "type": "module",
   "main": "webui/src/index.ts",

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-access"
-version = "0.1.22"
+version = "0.1.23"
 description = "GovOPlaN access platform module with identity, auth, RBAC, and scope primitives."
 readme = "README.md"
 requires-python = ">=3.12"

src/govoplan_access/__init__.py

@@ -1,3 +1,3 @@
 """GovOPlaN access platform module."""
 
-__version__ = "0.1.22"
+__version__ = "0.1.23"

src/govoplan_access/backend/manifest.py

@@ -862,6 +862,44 @@ ACCESS_DOCUMENTATION: tuple[DocumentationTopic, ...] = (
             ],
         },
     ),
+    DocumentationTopic(
+        id="access.reference.authentication-fields",
+        title="Authentication and password fields",
+        summary="Understand which credentials are used for interactive sign-in, initial account enrollment, administrative re-authorization, and automation.",
+        body=(
+            "The sign-in email identifies the account and the password authenticates only that account. Initial passwords entered by administrators are transmitted only for account creation; leaving the field empty asks the server to generate a one-time temporary password. Requiring a password change prevents that temporary credential from becoming the long-term credential. Current-password prompts re-authorize a sensitive action and never target the selected user's password. The automation API key in local settings is used only when no interactive browser session token is available; it should be a narrowly scoped, revocable key and must not be shared with other users. Generated passwords are not applied until Use password is selected."
+        ),
+        layer="always",
+        documentation_types=("admin", "user"),
+        audience=("user", "tenant_admin", "access_admin", "operator"),
+        order=29,
+        conditions=(DocumentationCondition(required_modules=("access",)),),
+        links=(
+            DocumentationLink(label="Sign in", href="/", kind="runtime"),
+            DocumentationLink(label="Access administration", href="/admin", kind="runtime"),
+            DocumentationLink(label="Local connection settings", href="/settings", kind="runtime"),
+        ),
+        translations={
+            "de": {
+                "title": "Authentifizierungs- und Passwortfelder",
+                "summary": "Einordnen, welche Zugangsdaten für die interaktive Anmeldung, die erste Kontoeinrichtung, die erneute administrative Autorisierung und Automatisierung verwendet werden.",
+                "body": (
+                    "Die Anmelde-E-Mail identifiziert das Konto; das Passwort authentifiziert ausschließlich dieses Konto. Von Administrierenden eingegebene Anfangspasswörter werden nur zur Kontoerstellung übertragen. Bleibt das Feld leer, erzeugt der Server ein einmaliges temporäres Passwort. Die Pflicht zum Passwortwechsel verhindert, dass diese temporäre Zugangsdaten dauerhaft verwendet werden. Die Abfrage des aktuellen Passworts autorisiert eine sensible Aktion erneut und meint niemals das Passwort der ausgewählten Person. Der Automatisierungs-API-Schlüssel in den lokalen Einstellungen wird nur verwendet, wenn kein interaktives Browser-Sitzungstoken verfügbar ist; er sollte eng begrenzt, widerrufbar und nicht mit anderen Personen geteilt sein. Generierte Passwörter werden erst mit „Passwort verwenden“ übernommen."
+                ),
+            }
+        },
+        metadata={
+            "kind": "reference",
+            "help_contexts": [
+                "access.authentication.email",
+                "access.authentication.password",
+                "access.settings.automation-api-key",
+                "access.admin.system-users.initial-password",
+                "access.admin.tenant-users.initial-password",
+                "access.admin.tenant-users.require-password-change",
+            ],
+        },
+    ),
     DocumentationTopic(
         id="access.workflow.grant-user-access",
         title="Grant a person access",
@@ -1531,6 +1569,7 @@ ACCESS_DOCUMENTATION: tuple[DocumentationTopic, ...] = (
                 "access.sessions.action.revoke",
                 "access.sessions.action.revoke-others",
                 "access.admin.user-sessions",
+                "access.sessions.field.current-password",
             ],
             "api_paths": [
                 "/api/v1/auth/sessions",
@@ -1921,7 +1960,7 @@ def _people_search(context: ModuleContext) -> object:
 manifest = ModuleManifest(
     id="access",
     name="Access",
-    version="0.1.22",
+    version="0.1.23",
     optional_dependencies=("identity", "organizations", "tenancy", "idm"),
     provides_interfaces=(
         ModuleInterfaceProvider(name=CAPABILITY_ACCESS_PEOPLE_SEARCH, version="0.1.0"),

webui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govoplan/access-webui",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "private": true,
   "type": "module",
   "scripts": {

webui/src/features/admin/SystemUsersPanel.tsx

@@ -239,8 +239,10 @@ export default function SystemUsersPanel({
           <FormField label="i18n:govoplan-access.email.84add5b2"><input value={draft.email} disabled={editing !== "new"} onChange={(event) => setDraft({ ...draft, email: event.target.value })} /></FormField>
           <FormField label="i18n:govoplan-access.display_name.c7874aaa"><input value={draft.displayName} disabled={editing !== "new" && !canUpdate} onChange={(event) => setDraft({ ...draft, displayName: event.target.value })} /></FormField>
           {editing === "new" &&
-          <FormField label="i18n:govoplan-access.initial_password.2278be8c">
+          <FormField label="i18n:govoplan-access.initial_password.2278be8c" helpContextId="access.admin.system-users.initial-password" helpModuleId="access">
               <PasswordField
+              helpContextId="access.admin.system-users.initial-password"
+              helpModuleId="access"
               value={draft.password}
               placeholder="i18n:govoplan-access.leave_empty_to_generate.e58222d8"
               autoComplete="new-password"

webui/src/features/admin/UsersPanel.tsx

@@ -249,6 +249,8 @@ export default function UsersPanel({ settings, auth, canCreate, canUpdate, canSu
       id: "revoke-session",
       label: "i18n:govoplan-access.revoke_session.5e551007",
       variant: "danger",
+      helpContextId: "access.sessions.action.revoke",
+      helpModuleId: "access",
       applicable: !row.current,
       disabled: busy || !canRevokeSessions,
       disabledReason: !canRevokeSessions ? "i18n:govoplan-access.session_revocation_permission_required.5e551016" : busy ? ACCESS_INTERFACE_I18N.operationInProgress : undefined,
@@ -283,8 +285,10 @@ export default function UsersPanel({ settings, auth, canCreate, canUpdate, canSu
           <FormField label="i18n:govoplan-access.email.84add5b2"><input value={draft.email} disabled={editing !== "new"} onChange={(event) => setDraft({ ...draft, email: event.target.value })} /></FormField>
           <FormField label="i18n:govoplan-access.display_name.c7874aaa"><input value={draft.displayName} disabled={editing !== "new" && !canUpdate} onChange={(event) => setDraft({ ...draft, displayName: event.target.value })} /></FormField>
           {editing === "new" &&
-          <FormField label="i18n:govoplan-access.initial_password.2278be8c">
+          <FormField label="i18n:govoplan-access.initial_password.2278be8c" helpContextId="access.admin.tenant-users.initial-password" helpModuleId="access">
               <PasswordField
+              helpContextId="access.admin.tenant-users.initial-password"
+              helpModuleId="access"
               value={draft.password}
               placeholder="i18n:govoplan-access.leave_empty_to_generate.e58222d8"
               autoComplete="new-password"
@@ -294,7 +298,7 @@ export default function UsersPanel({ settings, auth, canCreate, canUpdate, canSu
           }
           <FormField label="i18n:govoplan-access.membership_status.b77fc732"><select value={draft.isActive ? "active" : "inactive"} disabled={Boolean(editing && editing !== "new" && (!canSuspend || editing.is_last_active_owner))} onChange={(event) => setDraft({ ...draft, isActive: event.target.value === "active" })}><option value="active">i18n:govoplan-access.active.a733b809</option><option value="inactive">i18n:govoplan-access.inactive.09af574c</option></select></FormField>
         </FormGrid>
-        {editing === "new" && <ToggleSwitch label="i18n:govoplan-access.require_password_change_when_account_settings_ar.69bce7a3" checked={draft.passwordResetRequired} onChange={(passwordResetRequired) => setDraft({ ...draft, passwordResetRequired })} />}
+        {editing === "new" && <ToggleSwitch label="i18n:govoplan-access.require_password_change_when_account_settings_ar.69bce7a3" checked={draft.passwordResetRequired} helpContextId="access.admin.tenant-users.require-password-change" helpModuleId="access" onChange={(passwordResetRequired) => setDraft({ ...draft, passwordResetRequired })} />}
         {editing && editing !== "new" && editing.is_last_active_owner && <p className="admin-protection-note">i18n:govoplan-access.this_membership_is_the_tenant_s_last_active_oper.072b247f</p>}
         <ContentGrid columns={2} spacing="block" collapseAt="wide">
           <div><span className="form-label">i18n:govoplan-access.groups.ae9629f4</span><AdminSelectionList options={groups.filter((group) => group.is_active).map((group) => ({ id: group.id, label: group.name, description: group.description, disabled: !canManageGroups }))} selected={draft.groupIds} onChange={(groupIds) => setDraft({ ...draft, groupIds })} emptyText="i18n:govoplan-access.no_groups_exist_yet.9cd029f6" /></div>
@@ -320,11 +324,11 @@ export default function UsersPanel({ settings, auth, canCreate, canUpdate, canSu
         </>}
       </Dialog>
 
-      <Dialog variant="administration" size="large" open={Boolean(revokingSession)} title="i18n:govoplan-access.revoke_session.5e551007" onClose={() => !busy && setRevokingSession(null)} className="" footer={<><Button onClick={() => setRevokingSession(null)} disabled={busy}>i18n:govoplan-access.cancel.77dfd213</Button><Button variant="danger" onClick={() => void revokeSelectedSession()} disabled={busy || !reauthorizationPassword} disabledReason={!reauthorizationPassword ? "i18n:govoplan-access.current_password_required.5e551019" : busy ? ACCESS_INTERFACE_I18N.operationInProgress : undefined}>i18n:govoplan-access.revoke_session.5e551007</Button></>}>
+      <Dialog variant="administration" size="large" open={Boolean(revokingSession)} title="i18n:govoplan-access.revoke_session.5e551007" helpContextId="access.sessions.action.revoke" helpModuleId="access" onClose={() => !busy && setRevokingSession(null)} className="" footer={<><Button onClick={() => setRevokingSession(null)} disabled={busy}>i18n:govoplan-access.cancel.77dfd213</Button><Button variant="danger" helpContextId="access.sessions.action.revoke" helpModuleId="access" onClick={() => void revokeSelectedSession()} disabled={busy || !reauthorizationPassword} disabledReason={!reauthorizationPassword ? "i18n:govoplan-access.current_password_required.5e551019" : busy ? ACCESS_INTERFACE_I18N.operationInProgress : undefined}>i18n:govoplan-access.revoke_session.5e551007</Button></>}>
         {sessionError && <p className="admin-protection-note">{sessionError}</p>}
         <p>i18n:govoplan-access.admin_session_revocation_confirmation.5e551020</p>
-        <FormField label="i18n:govoplan-access.current_password.5e551021">
-          <PasswordField value={reauthorizationPassword} autoComplete="current-password" onValueChange={setReauthorizationPassword} />
+        <FormField label="i18n:govoplan-access.current_password.5e551021" helpContextId="access.sessions.field.current-password" helpModuleId="access">
+          <PasswordField helpContextId="access.sessions.field.current-password" helpModuleId="access" value={reauthorizationPassword} autoComplete="current-password" onValueChange={setReauthorizationPassword} />
         </FormField>
       </Dialog>
 

webui/src/features/sessions/SessionSettingsPanel.tsx

@@ -132,6 +132,8 @@ export default function SessionSettingsPanel({
                 id: "revoke",
                 label: "i18n:govoplan-access.revoke_session.5e551007",
                 variant: "danger",
+                helpContextId: "access.sessions.action.revoke",
+                helpModuleId: "access",
                 applicable: !row.current,
                 disabled: busy,
                 disabledReason: busy
@@ -208,6 +210,8 @@ export default function SessionSettingsPanel({
         destructiveActions={
           <Button
             variant="danger"
+            helpContextId="access.sessions.action.revoke-others"
+            helpModuleId="access"
             disabled={busy || sessions.filter((item) => !item.current).length === 0}
             disabledReason={
               busy
@@ -243,6 +247,8 @@ export default function SessionSettingsPanel({
         confirmLabel="i18n:govoplan-access.revoke_session.5e551007"
         tone="danger"
         busy={busy}
+        helpContextId="access.sessions.action.revoke"
+        helpModuleId="access"
         onCancel={() => setRevoking(null)}
         onConfirm={() => void revokeOne()}
       />
@@ -253,6 +259,8 @@ export default function SessionSettingsPanel({
         confirmLabel="i18n:govoplan-access.revoke_all_other_sessions.5e551012"
         tone="danger"
         busy={busy}
+        helpContextId="access.sessions.action.revoke-others"
+        helpModuleId="access"
         onCancel={() => setRevokingOthers(false)}
         onConfirm={() => void revokeOthers()}
       />