feat: Implement core data classes

Author: anubhav756

packages/toolbox-adk/src/toolbox_adk/credentials.py

@@ -0,0 +1,111 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dataclasses import dataclass
+from typing import Any, Optional, List, Dict
+from enum import Enum
+
+try:
+    from google.auth import credentials as google_creds
+except ImportError:
+    google_creds = None  # pragma: no cover
+
+
+class CredentialType(Enum):
+    TOOLBOX_IDENTITY = "TOOLBOX_IDENTITY"
+    APPLICATION_DEFAULT_CREDENTIALS = "APPLICATION_DEFAULT_CREDENTIALS"
+    USER_IDENTITY = "USER_IDENTITY"
+    MANUAL_TOKEN = "MANUAL_TOKEN"
+    MANUAL_CREDS = "MANUAL_CREDS"
+
+
+@dataclass
+class CredentialConfig:
+    type: CredentialType
+    # For APPLICATION_DEFAULT_CREDENTIALS
+    target_audience: Optional[str] = None
+    # For USER_IDENTITY
+    client_id: Optional[str] = None
+    client_secret: Optional[str] = None
+    scopes: Optional[List[str]] = None
+    # For MANUAL_TOKEN
+    token: Optional[str] = None
+    scheme: Optional[str] = None
+    # For MANUAL_CREDS
+    credentials: Optional[Any] = None  # google.auth.credentials.Credentials
+
+
+class CredentialStrategy:
+    """Factory for creating credential configurations for ToolboxToolset."""
+
+    @staticmethod
+    def TOOLBOX_IDENTITY() -> CredentialConfig:
+        """
+        No credentials are sent. Relies on the remote Toolbox server's own identity.
+        """
+        return CredentialConfig(type=CredentialType.TOOLBOX_IDENTITY)
+
+    @staticmethod
+    def APPLICATION_DEFAULT_CREDENTIALS(target_audience: str) -> CredentialConfig:
+        """
+        Uses the agent ADC to generate a Google-signed ID token for the specified audience.
+        This is suitable for Cloud Run, GKE, or local development with `gcloud auth login`.
+        """
+        return CredentialConfig(
+            type=CredentialType.APPLICATION_DEFAULT_CREDENTIALS,
+            target_audience=target_audience,
+        )
+
+    @staticmethod
+    def WORKLOAD_IDENTITY(target_audience: str) -> CredentialConfig:
+        """
+        Alias for APPLICATION_DEFAULT_CREDENTIALS.
+        """
+        return CredentialStrategy.APPLICATION_DEFAULT_CREDENTIALS(target_audience)
+
+    @staticmethod
+    def USER_IDENTITY(
+        client_id: str, client_secret: str, scopes: Optional[List[str]] = None
+    ) -> CredentialConfig:
+        """
+        Configures the ADK-native interactive 3-legged OAuth flow to get consent
+        and credentials from the end-user at runtime.
+        """
+        return CredentialConfig(
+            type=CredentialType.USER_IDENTITY,
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes,
+        )
+
+    @staticmethod
+    def MANUAL_TOKEN(token: str, scheme: str = "Bearer") -> CredentialConfig:
+        """
+        Send a hardcoded token string in the Authorization header.
+        """
+        return CredentialConfig(
+            type=CredentialType.MANUAL_TOKEN,
+            token=token,
+            scheme=scheme,
+        )
+
+    @staticmethod
+    def MANUAL_CREDS(credentials: Any) -> CredentialConfig:
+        """
+        Uses a provided Google Auth Credentials object.
+        """
+        return CredentialConfig(
+            type=CredentialType.MANUAL_CREDS,
+            credentials=credentials,
+        )

packages/toolbox-adk/tests/unit/test_credentials.py

@@ -0,0 +1,59 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from toolbox_adk.credentials import CredentialStrategy, CredentialType
+
+class TestCredentialStrategy:
+    def test_toolbox_identity(self):
+        config = CredentialStrategy.TOOLBOX_IDENTITY()
+        assert config.type == CredentialType.TOOLBOX_IDENTITY
+
+    def test_application_default_credentials(self):
+        audience = "https://example.com"
+        config = CredentialStrategy.APPLICATION_DEFAULT_CREDENTIALS(audience)
+        assert config.type == CredentialType.APPLICATION_DEFAULT_CREDENTIALS
+        assert config.target_audience == audience
+
+    def test_workload_identity_alias(self):
+        audience = "https://example.com"
+        config = CredentialStrategy.WORKLOAD_IDENTITY(audience)
+        assert config.type == CredentialType.APPLICATION_DEFAULT_CREDENTIALS
+        assert config.target_audience == audience
+
+    def test_user_identity(self):
+        config = CredentialStrategy.USER_IDENTITY(
+            client_id="id",
+            client_secret="secret",
+            scopes=["scope1"]
+        )
+        assert config.type == CredentialType.USER_IDENTITY
+        assert config.client_id == "id"
+        assert config.client_secret == "secret"
+        assert config.scopes == ["scope1"]
+
+    def test_manual_token(self):
+        config = CredentialStrategy.MANUAL_TOKEN(token="abc", scheme="Custom")
+        assert config.type == CredentialType.MANUAL_TOKEN
+        assert config.token == "abc"
+        assert config.scheme == "Custom"
+
+    def test_manual_token_defaults(self):
+        config = CredentialStrategy.MANUAL_TOKEN(token="abc")
+        assert config.scheme == "Bearer"
+
+    def test_manual_creds(self):
+        fake_creds = object()
+        config = CredentialStrategy.MANUAL_CREDS(fake_creds)
+        assert config.type == CredentialType.MANUAL_CREDS
+        assert config.credentials == fake_creds