simple_module_auth: expose a principal resolver that handles session cookie OR PAT bearer token

[antosubash]

Context

smpy_gis v1.0 roadmap (T3, see https://github.com/antosubash/smpy_gis/pull/15) introduces Personal Access Tokens for scripted access to the GIS module's /api/gis/* endpoints. The clean path is a single FastAPI dependency that resolves either a session cookie OR Authorization: Bearer pat_xxx, returning the same Principal shape downstream so every protected endpoint stays identical regardless of how the caller authenticated.

Current state (best guess — please correct)

simple_module_auth ships a session-cookie auth flow. I don't see a public hook for "plug in additional credential resolvers" — please point me at one if it exists.

Proposed shape

Two options:

A — built-in PAT facility in simple_module_auth: model + endpoints + admin UI for personal access tokens, with get_principal() accepting both auth modes. Most user-friendly; biggest upstream API surface.

B — extension hook so apps register their own resolver:

# in a module's on_startup
auth.principal_resolvers.append(my_pat_resolver)

where auth.get_principal falls through session → registered resolvers → 401. Smaller upstream surface; apps own their token storage.

Module-side leaning toward B — token storage is GIS-scoped (gis_personal_access_tokens table per the spec) so it doesn't belong upstream, but the resolver chain does.

Acceptance

• get_principal() (or equivalent) resolves session OR bearer in a documented order
• Existing session-only consumers unaffected (no breaking change)
• Documented example in docs.py.simplemodule.dev covering an app that adds a custom resolver

Timeline

Needed by end of M3 (smpy_gis 2026-08-31) to unblock the T3 PAT workstream.