Allow personal access tokens to enumerate readable groups for watchdogs

[Datawav]

Problem

Personal access tokens are intended for read-only forensic automation, but they currently authorize only:

GET /api/v1/groups/<exact-slug>/export/

The group slug is a 32-character opaque group reference. A read-only agent or watchdog cannot discover the slugs it is supposed to inspect, so it cannot monitor all groups or notice newly-created groups without a separate session-authenticated browser or an operator-maintained list.

This is an authentication/capability mismatch rather than an export-parser problem:

• forensics.views.api_group_list already returns goggles-groups/v1, but is guarded by @login_required.
• authenticate_reader() already accepts either a logged-in session or a valid PersonalAccessToken and explicitly reflects the current shared-internal-tenant model.
• The export endpoint uses authenticate_reader(), but requires an exact slug before authentication can return any useful data.

Requested capability

Allow a valid personal access token to enumerate the groups it may read. Either extend the existing endpoint or add a purpose-built token endpoint:

GET /api/v1/groups/
Authorization: Bearer <personal-access-token>

The response should remain a metadata index, not forensic evidence. At minimum each row needs:

• slug
• updated_at
• stable display name, if already exposed to authenticated users
• enough summary/version metadata to avoid downloading an unchanged full export

For efficient polling, also support at least one of:

• updated_since
• cursor pagination ordered by (updated_at, slug)
• ETag / If-None-Match

A poller can then fetch the full authenticated export only for groups whose metadata changed.

Security and compatibility requirements

• Accept only logged-in sessions or valid, active, unexpired PersonalAccessToken credentials. Upload tokens must remain invalid for reads.
• Route each group through the same object-level scope check used by the export path; do not assume the shared-tenant model will remain permanent.
• Return 401 JSON for missing/invalid bearer authentication rather than redirecting an API caller to the HTML login page.
• Do not include event evidence, decrypted payloads, source IPs, user agents, bearer-token metadata, or upload secrets.
• Keep the existing goggles-groups/v1 schema compatible if the existing route is reused.
• Bound response cost with pagination and indexes suitable for regular polling.

Acceptance criteria

• A valid personal access token can list every group it is authorized to export.
• A newly-created group appears without manual slug configuration.
• Session-authenticated behavior remains unchanged.
• Missing, malformed, inactive, expired, and owner-deactivated tokens are rejected.
• Upload tokens cannot enumerate groups.
• Authorization tests cover future group-scoped visibility, including not-found-style handling where applicable.
• Polling can determine that nothing changed without streaming every full group export.
• docs/api-v1.md documents the token-enabled index and its pagination/change-detection contract.

Operational use case

A read-only forensic watchdog checks approximately every thirteen minutes and remains silent unless it finds new fork evidence, failed/unrecoverable convergence, invalid/quarantined audit data, unresolved expected delivery, or an engine active while multiple epochs behind. Exact-slug-only access makes complete coverage impossible and silently misses new groups.