Add Google Group Management app-group-lifecycle plugin

[somethingnew2-0]

Takes over and rebases #498 (originally by @barborico) onto current main. See that PR for fuller description, validation, and screenshots.

What

Adds an opt-in example app-group-lifecycle plugin that mirrors each Access group to a Google group and links them via Okta group push (Okta then owns membership sync), plus the core-Access enablers it needs:

• OktaService gains group push-mapping create/delete/list helpers.
• Group-config plugin hooks become app-config aware (so a plugin's group schema/validation can reflect app-level settings, e.g. an email-prefix pattern), and gain an immutable field flag enforced host-side on update and rendered read-only in the UI.
• New ModifyGroupPluginData operation owns the plugin_data merge and fires group_updated only when a plugin's configuration actually changes — never on status-only writes, which would otherwise re-trigger reconciliation in a loop. Group plugin config is validated up front on create/update (400 instead of a later reconcile failure).
• The bulk-sync hook sync_all_group_membership is renamed to sync_all_groups (it reconciles all group state, not just membership), with a renamed access sync-app-groups CLI command.
• The image ships the plugin source under /app/plugins without installing it, so a downstream image opts in by pip-installing it.

Why this is a fresh rebase, not a merge

#498 was branched before three things now on main: the async-SQLAlchemy migration (#480/#481), the uv/ty toolchain (#507), and — most relevant — the async plugin interface (#511). So this isn't a mechanical rebase: every backend surface #498 added had to be reworked for async. The plugin's lifecycle hooks are now async def and receive the request AsyncSession; Okta calls are awaited; the blocking Cloud Identity client runs off the event loop via asyncio.to_thread; and the operation/router/CLI paths were converted to awaited async SQLAlchemy. The 19 original commits are re-expressed as 6 logically-grouped, async-native commits.

The plugin's own behavior (idempotent reconcile, Access-as-source-of-truth with backfill from live Google/Okta state, immutable group email, per-group sync status) is unchanged from #498 — see that PR's description and screenshots for the functional walkthrough.

Rebase and async conversion by Claude; original plugin design and implementation by @barborico in #498.

🤖 Generated with Claude Code

[Jeff-Rowell]

Heads up on backward compatibility: sync-app-group-memberships (this command) and the sync_all_group_membership hook both exist on main today, so this is a rename of already-shipped surface, not a net-new name. There is no compatibility alias, so:

• any external scheduler invoking access sync-app-group-memberships (for example a periodic job defined outside this repo) breaks with "No such command" on deploy; and
• any third-party lifecycle plugin still implementing sync_all_group_membership silently stops being invoked, since it no longer matches a hookspec.

[barborico]

Accepting this rename without a compatibility alias, intentionally. This ships as part of Access 2.0, which introduces a number of breaking changes (e.g. the async hook specs), so we're deliberately omitting the deprecated command/hook shims that would preserve backward compatibility. External schedulers and third-party plugins will need to move to the new sync-app-groups command and hook name as part of the 2.0 upgrade.

[Jeff-Rowell]

_delete_google_group is the only Google-side path that isn't tolerant of an already-absent group. Every read path (_lookup_google_group_id, _email_from_status, _owned_group_id) tolerates absence, but this bare delete().execute() does not.

In group_deleted the mapping unlink is wrapped in a best-effort try/except, but this call runs outside it. So if the Google group was already deleted out of band (or on a delete replay/retry, which the reconcile design intends to be safe), delete() raises, the group_deleted hook raises, and invoke_app_group_lifecycle_hook rolls back instead of committing. The "authoritative cleanup" the surrounding comment describes then fails on a group that is already gone.

Note it should NOT reuse _is_group_absent_error here: that treats 403 as absent, whose rationale ("a genuine permission problem surfaces on the subsequent create call") does not hold on the delete path. A 403 on delete most likely means the service account lacks delete permission on a group that still exists; swallowing it would log a phantom successful deletion and leak the group. Only a true 404 is an unambiguous "already gone":

Suggested change

	async def _delete_google_group(self, google_group_id: str) -> None:
	await asyncio.to_thread(lambda: self._groups_api.delete(name=self._resource_name(google_group_id)).execute())
	async def _delete_google_group(self, google_group_id: str) -> None:
	try:
	await asyncio.to_thread(lambda: self._groups_api.delete(name=self._resource_name(google_group_id)).execute())
	except HttpError as e:
	# 404 -> already gone, so a delete replay is a no-op. Deliberately 404-only (not
	# _is_group_absent_error): a 403 on delete more likely means we lack permission on a
	# group that still exists, which must surface rather than masquerade as a deletion.
	if getattr(getattr(e, "resp", None), "status", None) != 404:
	raise

(One thing to confirm: that Cloud Identity's groups.delete returns 404, not a conflated 403, for an already-deleted group. If it returns 403, a replay would still error here, which is the safe direction.)

[somethingnew2-0]

Can we rebase this off of #552 and add this plugin install as optional, but enable it via a build argument in the docker-image.yml Github Action?

[somethingnew2-0]

We don't have any other frontend tests and nothing runs them in CI. Do we want to start including these or should they be removed?

[barborico]

Adding frontend test framework in #564.

[somethingnew2-0]

Should ModifyGroupDetails call into this new operation instead of it running invoke_app_group_lifecycle_hook(AppGroupLifecycleHook.GROUP_UPDATED...) itself?

[somethingnew2-0]

Not sure how much I like plugins being able to call Access API methods directly. I wonder if there's a way we can expose the Okta group mapping methods via the plugin interface?

[somethingnew2-0]

Feels weird to allow the plugin to query the Access database directly, should the app groups be passed into this plugin method instead or maybe accessible from the app parameter?