feat(storage)!: enforce AuthorizedSqlStore usage for APIs requiring access control (#5776)

## Summary

- Rename `sqlstore_impl` → `_sqlstore_impl` (private) and introduce
`authorized_sqlstore()` factory as the only supported way to obtain a
SQL store for API use
- Replace all direct `sqlstore_impl` + `AuthorizedSqlStore` two-step
patterns across providers with the new single-call
`authorized_sqlstore()` factory
- Add a pre-commit hook (`enforce-authorized-sqlstore`) that blocks
direct `_sqlstore_impl` usage outside `core/storage/sqlstore/`
- Remove the unused `agent_state` KVStore from responses persistence
config, completing the migration from #5757

## Test plan

- [ ] Unit tests pass: `uv run pytest tests/unit/ -x --tb=short`
- [ ] Pre-commit checks pass: `uv run pre-commit run --all-files`
- [ ] Integration tests pass in replay mode
- [ ] Verify the new pre-commit hook catches direct `sqlstore_impl`
usage

Signed-off-by: Sébastien Han <seb@redhat.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: leseb

.pre-commit-config.yaml

@@ -308,6 +308,26 @@ repos:
             }
             exit 0
 
+      - id: enforce-authorized-sqlstore
+        name: Enforce AuthorizedSqlStore usage
+        entry: bash
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true
+        files: ^src/
+        args:
+          - -c
+          - |
+            grep -rn --include="*.py" -E 'sqlstore_impl' src/ \
+              | grep -v 'core/storage/sqlstore/' && {
+              echo;
+              echo "❌ Direct sqlstore_impl usage is not allowed outside core/storage/sqlstore/.";
+              echo "Use authorized_sqlstore() from ogx.core.storage.sqlstore.authorized_sqlstore instead.";
+              echo;
+              exit 1;
+            } || true
+
       - id: check-file-size
         name: Check Python file size limit
         entry: python scripts/check_file_size.py

docs/docs/providers/responses/inline_builtin.mdx

@@ -15,9 +15,6 @@ Meta's reference implementation of an agent system that can use tools, access ve
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `persistence` | `ResponsesPersistenceConfig` | No |  |  |
-| `persistence.agent_state` | `KVStoreReference` | No |  |  |
-| `persistence.agent_state.namespace` | `str` | No |  | Key prefix for KVStore backends |
-| `persistence.agent_state.backend` | `str` | No |  | Name of backend from storage.backends |
 | `persistence.responses` | `ResponsesStoreReference` | No |  |  |
 | `persistence.responses.table_name` | `str` | No | openai_responses | Name of the table to use for storing OpenAI responses |
 | `persistence.responses.backend` | `str` | No |  | Name of backend from storage.backends |
@@ -98,9 +95,6 @@ Be concise, structured, and focused on helping the next LLM seamlessly continue
 
 ```yaml
 persistence:
-  agent_state:
-    namespace: agents
-    backend: kv_default
   responses:
     table_name: responses
     backend: sql_default

src/ogx/core/connectors/connectors.py

@@ -12,8 +12,7 @@
 
 from ogx.core.access_control.datatypes import AccessRule
 from ogx.core.datatypes import StackConfig
-from ogx.core.storage.sqlstore.authorized_sqlstore import AuthorizedSqlStore
-from ogx.core.storage.sqlstore.sqlstore import sqlstore_impl
+from ogx.core.storage.sqlstore.authorized_sqlstore import authorized_sqlstore
 from ogx.log import get_logger
 from ogx.providers.utils.tools.mcp import get_mcp_server_info, list_mcp_tools
 from ogx_api import (
@@ -61,8 +60,7 @@ def __init__(self, config: ConnectorServiceConfig):
         if not connectors_ref:
             raise ServiceNotEnabledError("storage.stores.connectors")
 
-        base_sql_store = sqlstore_impl(connectors_ref)
-        self.sql_store = AuthorizedSqlStore(base_sql_store, self.policy)
+        self.sql_store = authorized_sqlstore(connectors_ref, self.policy)
 
     async def initialize(self) -> None:
         """Initialize the connector service."""

src/ogx/core/conversations/conversations.py

@@ -13,8 +13,7 @@
 from ogx.core.access_control.datatypes import AccessRule
 from ogx.core.conversations.validation import CONVERSATION_ID_PATTERN
 from ogx.core.datatypes import StackConfig
-from ogx.core.storage.sqlstore.authorized_sqlstore import AuthorizedSqlStore
-from ogx.core.storage.sqlstore.sqlstore import sqlstore_impl
+from ogx.core.storage.sqlstore.authorized_sqlstore import authorized_sqlstore
 from ogx.log import get_logger
 from ogx_api import (
     Api,
@@ -74,8 +73,7 @@ def __init__(self, config: ConversationServiceConfig, deps: dict[Api, Any]):
         if not conversations_ref:
             raise ServiceNotEnabledError("storage.stores.conversations")
 
-        base_sql_store = sqlstore_impl(conversations_ref)
-        self.sql_store = AuthorizedSqlStore(base_sql_store, self.policy)
+        self.sql_store = authorized_sqlstore(conversations_ref, self.policy)
 
     async def initialize(self) -> None:
         """Initialize the store and create tables."""

src/ogx/core/prompts/prompts.py

@@ -11,8 +11,7 @@
 
 from ogx.core.access_control.datatypes import AccessRule
 from ogx.core.datatypes import StackConfig
-from ogx.core.storage.sqlstore.authorized_sqlstore import AuthorizedSqlStore
-from ogx.core.storage.sqlstore.sqlstore import sqlstore_impl
+from ogx.core.storage.sqlstore.authorized_sqlstore import authorized_sqlstore
 from ogx_api import (
     Api,
     CreatePromptRequest,
@@ -62,8 +61,7 @@ def __init__(self, config: PromptServiceConfig, deps: dict[Api, Any]):
         if not prompts_ref:
             raise ServiceNotEnabledError("storage.stores.prompts")
 
-        base_sql_store = sqlstore_impl(prompts_ref)
-        self.sql_store = AuthorizedSqlStore(base_sql_store, self.policy)
+        self.sql_store = authorized_sqlstore(prompts_ref, self.policy)
 
     async def initialize(self) -> None:
         await self.sql_store.create_table(

src/ogx/core/storage/sqlstore/__init__.py

@@ -14,4 +14,5 @@
     SqlStore as SqlStore,
 )
 
+from .authorized_sqlstore import authorized_sqlstore as authorized_sqlstore
 from .sqlstore import *  # noqa: F401,F403

src/ogx/core/storage/sqlstore/authorized_sqlstore.py

@@ -20,7 +20,8 @@
 from ogx.core.access_control.datatypes import AccessRule, Action, Scope
 from ogx.core.datatypes import User
 from ogx.core.request_headers import get_authenticated_user
-from ogx.core.storage.datatypes import StorageBackendType
+from ogx.core.storage.datatypes import SqlStoreReference, StorageBackendType
+from ogx.core.storage.sqlstore.sqlstore import _sqlstore_impl
 from ogx.log import get_logger
 from ogx_api import PaginatedResponse
 from ogx_api.internal.sqlstore import ColumnDefinition, ColumnType, SqlStore
@@ -81,6 +82,14 @@ def __init__(self, record_id: str, table_name: str, owner: User | None):
         self.owner = owner
 
 
+def authorized_sqlstore(reference: SqlStoreReference, policy: list[AccessRule]) -> "AuthorizedSqlStore":
+    """Create an AuthorizedSqlStore from a store reference and access policy.
+
+    This is the only supported way to obtain a SQL store for API use.
+    """
+    return AuthorizedSqlStore(_sqlstore_impl(reference), policy)
+
+
 class AuthorizedSqlStore:
     """
     Authorization layer for SqlStore that provides access control functionality.

src/ogx/core/storage/sqlstore/sqlstore.py

@@ -45,7 +45,7 @@ def get_pip_packages(store_config: dict | SqlStoreConfig) -> list[str]:
         return store_config.pip_packages()
 
 
-def sqlstore_impl(reference: SqlStoreReference) -> SqlStore:
+def _sqlstore_impl(reference: SqlStoreReference) -> SqlStore:
     """Get or create a SqlStore instance for the given store reference.
 
     Args:

src/ogx/distributions/ci-tests/config.yaml

@@ -211,9 +211,6 @@ providers:
     provider_type: inline::builtin
     config:
       persistence:
-        agent_state:
-          namespace: agents
-          backend: kv_default
         responses:
           table_name: responses
           backend: sql_default

src/ogx/distributions/ci-tests/run-with-postgres-store.yaml

@@ -211,9 +211,6 @@ providers:
     provider_type: inline::builtin
     config:
       persistence:
-        agent_state:
-          namespace: agents
-          backend: kv_default
         responses:
           table_name: responses
           backend: sql_default