Manage designated Funktionsuser (machine accounts) as an explicit exception to the people boundary

[2000game]

Context

ct-cli never manages people or memberships. That boundary stays. But the connector depends on a handful of machine accounts, the members of the Funktionsuser Merkmal (funktionsuser: prod 1993, dev 1789, declared in eqrm/ct-structure's ct.config.ts). Each authenticates with a login token.

These accounts are infrastructure, not people. Today they are created by hand per instance, their permissions drift between prod and dev, and their tokens live wherever someone pasted them. Standing staging up against eqrm-dev (eqrm/churchtools-connector#1469) hit exactly this: every machine user has to be recreated on dev by hand.

Ask

A narrow, opt-in way to declare named machine users, and nothing else:

• the account itself (a synthetic person with a reserved name, .invalid e-mail, no real person data)
• its membership and group role in funktionsuser
• its permissions, via that role's grants (already in ct-structure's scope)
• optionally, login-token issue/rotation with the token written to AWS Secrets Manager, never to stdout or state

It must stay impossible to declare a real person. For example: only members of funktionsuser, only with a reserved name prefix, and a hard refusal otherwise. scripts/seed-dev-permission-cohort.ts in ct-structure already shows the dev-only, no-delete, idempotent pattern for synthetic people outside declared state.

Out of scope

Real people, arbitrary memberships, deletes.

[2000game]

Additional requirement (from Felix): traceability, not just provisioning.

For every functional account it must be declared and reviewable:

• which permissions it holds
• why: the consumer that needs each one, e.g. "connector SyncPcoTeamRolesJob reads /persons/{id}/groups", or "kids check-in writes group meetings"
• through which path: the Funktionsuser group-role grant, a membership in another rights-bearing group, or a direct personal permission

ct plan should flag any permission the account actually holds that has no declared reason and path, the same way undeclared grants show up as drift today. The goal is that "why can this bot do X?" is answered by the config, not by forensics. The connector's ct-attribution-forensics skill exists because that question is currently hard.

[2000game]

Token issuance constraint (found 2026-09-25 while creating dev person 248, Stella Staging): ChurchTools does not let even an admin read another person's login token (GET /persons/{id}/logintoken returns 403 "Forbidden to see Login Token"), and it refuses the read during simulation ("Cannot get login token in simulation"). The only API path is a real password login as the functional account, then reading its own token (the same flow as loginWithPassword in src/auth/login.ts). So managing functional accounts has to include their username and password (or an out-of-band UI step) just to issue or rotate a token. Design for that: e.g. generate a random password, log in once, write the token to Secrets Manager, and never persist the password.

[2000game]

And the password can't be set by API either. PUT /persons/{personId}/password ignores personId and changes the password of the currently signed-in account (it also invalidates all of that account's sessions and login tokens). An admin session therefore cannot give a functional account its first password through the REST API. Running it as the admin would change the admin's own password. POST /persons/{id}/invite and /reset-password need a deliverable e-mail, which a synthetic .invalid account deliberately lacks. Today the first password has to be set in the ChurchTools UI; any automation would need a legacy/internal endpoint, which is unverified.

[2000game]

Outcome for dev person 248 (Stella Staging): the first password is set by hand through a real-mailbox invite. Takeaway for this issue: a functional account needs a real, shared mailbox (e.g. one eqrm.de address with plus-addressing per account). Without one it can't be invited, so it can't get a password, so its login token can't be read. That makes a real e-mail a prerequisite of any automated issue/rotate flow.