Add Supabase tenant extension as built-in (#267)

Move the Supabase tenant extension into the hindsight-api package so users
can enable it with just an environment variable — no file copying or Docker
image modifications needed.

Key improvements over the original submission:
- JWKS-based local JWT verification (no network call per request) with
  automatic fallback to /auth/v1/user for legacy HS256 projects
- Service key is now optional (only needed for HS256 or health checks)
- UUID validation on user IDs before schema name construction
- Schema prefix validation against Postgres identifier rules
- Key rotation handling with automatic JWKS cache refresh
- Proper logging via Python logging module
- Tenant extension lifecycle hooks (on_startup/on_shutdown) wired into
  the server lifespan
- Public tenant_extension property on MemoryEngine
- 54 unit tests covering both verification modes, cache behavior, error
  paths, and the extension loader
- README updated to reflect JWKS-first architecture

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: jerryhenley

hindsight-api/hindsight_api/api/http.py

@@ -1432,6 +1432,12 @@ async def lifespan(app: FastAPI):
             poller_task = asyncio.create_task(poller.run())
             logging.info(f"Worker poller started (worker_id={worker_id})")
 
+        # Call tenant extension startup hook (e.g. JWKS fetch for Supabase)
+        tenant_extension = memory.tenant_extension
+        if tenant_extension:
+            await tenant_extension.on_startup()
+            logging.info("Tenant extension started")
+
         # Call HTTP extension startup hook
         if http_extension:
             await http_extension.on_startup()
@@ -1450,6 +1456,11 @@ async def lifespan(app: FastAPI):
                     pass
             logging.info("Worker poller stopped")
 
+        # Call tenant extension shutdown hook
+        if tenant_extension:
+            await tenant_extension.on_shutdown()
+            logging.info("Tenant extension stopped")
+
         # Call HTTP extension shutdown hook
         if http_extension:
             await http_extension.on_shutdown()

hindsight-api/hindsight_api/engine/memory_engine.py

@@ -467,6 +467,11 @@ def __init__(
             tenant_extension = DefaultTenantExtension(config={})
         self._tenant_extension = tenant_extension
 
+    @property
+    def tenant_extension(self) -> "TenantExtension | None":
+        """The configured tenant extension, if any."""
+        return self._tenant_extension
+
     async def _validate_operation(self, validation_coro) -> None:
         """
         Run validation if an operation validator is configured.

hindsight-api/hindsight_api/extensions/__init__.py

@@ -16,7 +16,7 @@
 """
 
 from hindsight_api.extensions.base import Extension
-from hindsight_api.extensions.builtin import ApiKeyTenantExtension
+from hindsight_api.extensions.builtin import ApiKeyTenantExtension, SupabaseTenantExtension
 from hindsight_api.extensions.context import DefaultExtensionContext, ExtensionContext
 from hindsight_api.extensions.http import HttpExtension
 from hindsight_api.extensions.loader import load_extension
@@ -80,6 +80,7 @@
     "MentalModelRefreshResult",
     # Tenant/Auth
     "ApiKeyTenantExtension",
+    "SupabaseTenantExtension",
     "AuthenticationError",
     "RequestContext",
     "Tenant",

hindsight-api/hindsight_api/extensions/builtin/__init__.py

@@ -6,13 +6,17 @@
 
 Available built-in extensions:
     - ApiKeyTenantExtension: Simple API key validation with public schema
+    - SupabaseTenantExtension: Supabase JWT validation with per-user schema isolation
 
 Example usage:
     HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
+    HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.supabase_tenant:SupabaseTenantExtension
 """
 
+from hindsight_api.extensions.builtin.supabase_tenant import SupabaseTenantExtension
 from hindsight_api.extensions.builtin.tenant import ApiKeyTenantExtension
 
 __all__ = [
     "ApiKeyTenantExtension",
+    "SupabaseTenantExtension",
 ]