stackos-connectors 0.2.0__tar.gz → 0.2.1__tar.gz

{stackos_connectors-0.2.0 → stackos_connectors-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackos-connectors
-Version: 0.2.0
+Version: 0.2.1
 Summary: Named provider connectors with plain data and caller-owned authentication.
 License-Expression: MIT
 License-File: LICENSE

{stackos_connectors-0.2.0 → stackos_connectors-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stackos-connectors"
-version = "0.2.0"
+version = "0.2.1"
 description = "Named provider connectors with plain data and caller-owned authentication."
 readme = "README.md"
 requires-python = ">=3.12"

{stackos_connectors-0.2.0 → stackos_connectors-0.2.1}/src/stackos_connectors/auth.py

@@ -143,6 +143,17 @@ def get_auth_contract(
     return contract
 
 
+def scope_satisfies(connector: str, required: str, granted: set[str]) -> bool:
+    """Report documented scope compatibility; the consumer owns enforcement."""
+    if required in granted:
+        return True
+    if connector == "google-search-console":
+        from .connectors.google_search_console.auth import READ_SCOPE, WRITE_SCOPE
+
+        return required == READ_SCOPE and WRITE_SCOPE in granted
+    return False
+
+
 def build_authorization_request(
     connector: str,
     *,

stackos_connectors-0.2.1/src/stackos_connectors/connectors/google_search_console/auth.py

@@ -0,0 +1,19 @@
+"""Search Console's explicit read and sitemap-submission OAuth scopes."""
+
+from dataclasses import replace
+
+from ...auth import OAuthTokenError
+
+READ_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly"
+WRITE_SCOPE = "https://www.googleapis.com/auth/webmasters"
+
+
+def resolve_contract(contract, config):
+    mode = config.get("access_mode", "readonly")
+    if mode not in ("readonly", "sitemap_write"):
+        raise OAuthTokenError(
+            "Search Console access mode must be readonly or sitemap_write",
+            provider_key=contract.provider_key,
+            invalid_fields=("access_mode",),
+        )
+    return replace(contract, scopes=(WRITE_SCOPE if mode == "sitemap_write" else READ_SCOPE,))

{stackos_connectors-0.2.0 → stackos_connectors-0.2.1}/src/stackos_connectors/connectors/google_search_console/catalog.json

@@ -23,7 +23,16 @@
       },
       "config_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "access_mode": {
+            "type": "string",
+            "enum": [
+              "readonly",
+              "sitemap_write"
+            ],
+            "default": "readonly"
+          }
+        },
         "required": []
       },
       "payload_format": "json",
@@ -49,6 +58,24 @@
             "required": true,
             "secret": true,
             "type": "secret"
+          },
+          {
+            "key": "access_mode",
+            "label": "Access",
+            "type": "select",
+            "secret": false,
+            "required": false,
+            "options": [
+              {
+                "value": "readonly",
+                "label": "Read only"
+              },
+              {
+                "value": "sitemap_write",
+                "label": "Read and submit sitemaps"
+              }
+            ],
+            "description": "Defaults to read only. Changing access requires acquiring a token with the selected scope."
           }
         ],
         "description": "The consumer handles Google browser consent, state and callbacks. Exchange the resulting authorization code with request_token. Execution accepts the resolved access_token; credential storage and refresh scheduling remain consumer-owned.",
@@ -80,7 +107,16 @@
       },
       "config_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "access_mode": {
+            "type": "string",
+            "enum": [
+              "readonly",
+              "sitemap_write"
+            ],
+            "default": "readonly"
+          }
+        },
         "required": []
       },
       "payload_format": "json",
@@ -96,6 +132,24 @@
             "required": true,
             "secret": true,
             "type": "secret"
+          },
+          {
+            "key": "access_mode",
+            "label": "Access",
+            "type": "select",
+            "secret": false,
+            "required": false,
+            "options": [
+              {
+                "value": "readonly",
+                "label": "Read only"
+              },
+              {
+                "value": "sitemap_write",
+                "label": "Read and submit sitemaps"
+              }
+            ],
+            "description": "Defaults to read only. Changing access requires acquiring a token with the selected scope."
           }
         ],
         "description": "Obtain a Google access token with the required provider scopes and permissions before execution.",
@@ -126,7 +180,16 @@
       },
       "config_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "access_mode": {
+            "type": "string",
+            "enum": [
+              "readonly",
+              "sitemap_write"
+            ],
+            "default": "readonly"
+          }
+        },
         "required": []
       },
       "payload_format": "json",
@@ -162,6 +225,24 @@
             "required": true,
             "secret": true,
             "type": "secret"
+          },
+          {
+            "key": "access_mode",
+            "label": "Access",
+            "type": "select",
+            "secret": false,
+            "required": false,
+            "options": [
+              {
+                "value": "readonly",
+                "label": "Read only"
+              },
+              {
+                "value": "sitemap_write",
+                "label": "Read and submit sitemaps"
+              }
+            ],
+            "description": "Defaults to read only. Changing access requires acquiring a token with the selected scope."
           }
         ],
         "description": "Exchange the Google refresh token for an access token with an explicit request_token call. Execution accepts the resolved access_token; credential storage and refresh scheduling remain consumer-owned.",
@@ -192,7 +273,16 @@
       },
       "config_schema": {
         "type": "object",
-        "properties": {},
+        "properties": {
+          "access_mode": {
+            "type": "string",
+            "enum": [
+              "readonly",
+              "sitemap_write"
+            ],
+            "default": "readonly"
+          }
+        },
         "required": []
       },
       "payload_format": "json",
@@ -208,6 +298,24 @@
             "required": true,
             "secret": true,
             "type": "secret"
+          },
+          {
+            "key": "access_mode",
+            "label": "Access",
+            "type": "select",
+            "secret": false,
+            "required": false,
+            "options": [
+              {
+                "value": "readonly",
+                "label": "Read only"
+              },
+              {
+                "value": "sitemap_write",
+                "label": "Read and submit sitemaps"
+              }
+            ],
+            "description": "Defaults to read only. Changing access requires acquiring a token with the selected scope."
           }
         ],
         "description": "Use request_token with the Google service-account key to acquire an access token. Execution accepts the resolved access_token; provider resource access must be granted separately. Credential storage and refresh scheduling remain consumer-owned.",
@@ -778,5 +886,6 @@
         "consent"
       ]
     ]
-  }
+  },
+  "auth_implementation": "stackos_connectors.connectors.google_search_console.auth:resolve_contract"
 }

{stackos_connectors-0.2.0 → stackos_connectors-0.2.1}/src/stackos_connectors/connectors/google_search_console/docs/auth.md

@@ -9,6 +9,18 @@ The [bundled catalog](../catalog.json) is the installed contract for method fiel
 | `oauth2_refresh_token` | `refresh_token` |
 | `service-account` | `jwt_bearer` |
 
+All four methods expose `access_mode`: omitted or `readonly` requests
+`https://www.googleapis.com/auth/webmasters.readonly`; explicit `sitemap_write`
+requests `https://www.googleapis.com/auth/webmasters`. Keep the saved selection
+when renewing a service-account token. Changing it requires fresh grant evidence;
+OAuth consent must be repeated when a new scope is needed. Selecting a mode does
+not expand a manually supplied token's permissions.
+
+The full `webmasters` scope also permits read operations. Consumers can use
+`stackos_connectors.auth.scope_satisfies` to check that documented relationship
+without changing stored provider scope evidence. Read-only scope never satisfies
+a sitemap submission requirement. Property permissions remain separate.
+
 Service-account token success does not establish Search Console property access. Inventory probes can succeed with no properties. Google Indexing is a separate resolved-token contract; no new Indexing JWT grant is supplied.
 
 `request_token` receives resolved application/key fields and performs only the requested grant. Actions and `probe_credentials` receive resolved execution fields. Discovery, probes and actions never acquire or refresh implicitly. The consumer owns credential/state/PKCE custody, callbacks, refresh timing and concurrency, permissions, persistence and audit. Token results and authorization URLs are sensitive in-process values.

stackos_connectors-0.2.1/tests/auth/test_search_console_scopes.py

@@ -0,0 +1,59 @@
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+from stackos_connectors import ConnectorAuth, auth, describe
+
+READ = "https://www.googleapis.com/auth/webmasters.readonly"
+WRITE = "https://www.googleapis.com/auth/webmasters"
+
+
+@pytest.mark.parametrize(
+    "method",
+    ["oauth2_authorization_code", "oauth2_access_token", "oauth2_refresh_token", "service-account"],
+)
+def test_explicit_write_mode_and_default_readonly(method):
+    assert auth.get_auth_contract("google-search-console", method=method).scopes == (READ,)
+    assert auth.get_auth_contract(
+        "google-search-console", method=method, config={"access_mode": "sitemap_write"}
+    ).scopes == (WRITE,)
+    with pytest.raises(auth.OAuthTokenError) as caught:
+        auth.get_auth_contract(
+            "google-search-console", method=method, config={"access_mode": "SECRET-invalid"}
+        )
+    assert "SECRET-invalid" not in str(caught.value)
+    assert caught.value.invalid_fields == ("access_mode",)
+
+
+def test_catalog_exposes_write_choice_on_each_existing_method():
+    for method in describe("google-search-console")["auth_methods"]:
+        field = next(f for f in method["setup"]["fields"] if f["key"] == "access_mode")
+        assert not field["secret"] and not field["required"]
+        assert [option["value"] for option in field["options"]] == ["readonly", "sitemap_write"]
+        assert method["config_schema"]["properties"]["access_mode"]["enum"] == [
+            "readonly",
+            "sitemap_write",
+        ]
+
+
+def test_write_consent_requests_only_explicit_scope():
+    request = auth.build_authorization_request(
+        "google-search-console",
+        auth=ConnectorAuth(
+            "oauth2_authorization_code",
+            {"client_id": "synthetic-app"},
+            config={"access_mode": "sitemap_write"},
+        ),
+        redirect_uri="https://consumer.example/callback",
+        state="synthetic-state",
+    )
+    assert parse_qs(urlparse(request.url).query)["scope"] == [WRITE]
+
+
+def test_scope_compatibility_is_one_way_and_provider_specific():
+    assert auth.scope_satisfies("google-search-console", READ, {WRITE})
+    assert auth.scope_satisfies("google-search-console", WRITE, {WRITE})
+    assert not auth.scope_satisfies("google-search-console", WRITE, {READ})
+    assert not auth.scope_satisfies("google-analytics", READ, {WRITE})
+    assert not auth.scope_satisfies("google-search-console", "invented", {WRITE})
+    assert auth.scope_satisfies("google-analytics", "exact", {"exact"})