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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackos-connectors
-Version: 0.1.0
+Version: 0.2.0
 Summary: Named provider connectors with plain data and caller-owned authentication.
 License-Expression: MIT
 License-File: LICENSE
@@ -20,8 +20,10 @@ A Python library of named provider connectors. A caller supplies a connector,
 action, input data and resolved authentication. The library maps that action to
 the provider protocol and returns provider output, metadata and file descriptors.
 
-The consumer owns credential storage and refresh, authorization, persistent state,
-workflow decisions and audit. Provider implementations use plain contracts and
+The consumer owns credential storage, when to authorize or refresh, persistent
+state, workflow decisions and audit. Explicit package functions implement provider
+authorization URLs, token grants, probes and signature checks. They never start
+authorization, refresh tokens or persist state implicitly. Provider implementations use plain contracts and
 can accept caller-owned HTTP clients, rate buckets and native protocol sessions.
 
 Each integration is grouped under `src/stackos_connectors/connectors/`:
@@ -71,6 +73,74 @@ execution; existing names cannot be replaced.
 `CallOptions.timeout=None` preserves each provider's default. A numeric timeout
 overrides that default. A supplied HTTP client remains caller-owned.
 
+## Explicit authentication
+
+`get_auth_contract(connector, method=..., config=...)` reads immutable provider
+facts from the bundled catalog. `build_authorization_request` formats a consent
+URL using the caller's redirect URI, state and optional PKCE challenge. The caller
+opens that URL, handles the callback and checks its state. `request_token` performs
+one requested `authorization_code`, `refresh_token`, `client_credentials` or
+`jwt_bearer` grant, where the selected method declares support. Meta's declared
+second token exchange is part of that explicit request.
+
+```python
+from stackos_connectors import ConnectorAuth, request_token
+
+token = await request_token(
+    "google-search-console",
+    auth=ConnectorAuth(
+        method="oauth2_authorization_code",
+        fields={"client_id": client_id, "client_secret": client_secret},
+    ),
+    grant_type="authorization_code",
+    code=validated_callback_code,
+    redirect_uri=registered_redirect_uri,
+    code_verifier=stored_pkce_verifier,
+    http=caller_http,
+)
+```
+
+Grant calls accept resolved application/key fields; action and probe calls accept
+the method's resolved execution fields, usually an access token. The catalog's
+`setup` and `protocol` describe acquisition separately from `fields_schema` and
+`config_schema`. Manual token methods retain their declared refresh compatibility;
+the library does not infer an auth method from token shape.
+
+`TokenResult` holds sensitive in-process values. An absent `refresh_token` means
+the response did not rotate it. `scopes_present=False` distinguishes omitted
+scope evidence from an explicitly empty grant. For a successful Google JWT grant,
+the immutable contract supplies the signed request's scopes; the consumer can
+apply the reviewed omission rule without changing the token response's provenance.
+The caller decides how to preserve prior evidence, enforce permissions and store
+results. `OAuthTokenError` exposes bounded categories/status and repair facts,
+without raw provider response bodies. Repr suppression is not a storage policy.
+
+`probe_credentials(connector, auth=..., options=..., context=...)` explicitly
+tests a resolved credential through a fixed provider binding. It returns safe
+provider facts and optional `AuthProbeEvidence`; it does not establish application
+readiness or permissions. `project_probe_config` projects portable config and
+retains supported legacy probe aliases. The caller chooses the IMAP native mailbox
+through `CallOptions(provider_context={"mailbox": ...})`. Google Ads/Workspace
+service-account probes only report resolved-token presence and unverified resource
+access; they make no HTTP call or new-grant claim.
+
+Google JWT validation/signing is shared across the five declared service-account
+methods. Credentials never come from ambient identity or key-supplied endpoints.
+Provider details live in `connectors/<provider>/docs/auth.md` and the catalog.
+Google Indexing retains its existing resolved-token action/probe contract; this
+release adds no Indexing JWT acquisition method.
+
+Provider-local pure helpers cover Telegram authorization request/challenge/state
+translation (`connectors.telegram.auth`), Slack v0 HMAC verification
+(`connectors.slack_bot.auth.verify_signature_v0`) and HubSpot v3 HMAC verification
+(`connectors.hubspot.signature.verify_signature_v3`). Callers own native sessions,
+encrypted custody, challenge expiry, ingress routing, trusted canonical URI,
+timestamp/replay checks and policy. HubSpot v2 verification is not implemented.
+
+No library call to discovery, probe or action execution starts an authorization
+flow, refreshes a token, opens a native session, stores credentials or selects
+readiness. Remote token revocation is not part of this API.
+
 For file-producing actions, pass `CallOptions(output_dir=Path(...))` and consume
 the plain descriptors in `result.files`. The library does not create application
 artifacts or public download URLs. Telegram actions require an already authorized
@@ -118,10 +188,10 @@ Python 3.12 or newer is required. Source:
 Published releases can be installed with:
 
 ```bash
-python -m pip install stackos-connectors==0.1.0
+python -m pip install stackos-connectors==0.2.0
 ```
 
-Or add `stackos-connectors==0.1.0` to your Python dependency requirements.
+Or add `stackos-connectors==0.2.0` to your Python dependency requirements.
 
 Install from a local checkout with `pip install /path/to/StackOSConnectors`, or
 build a wheel with `python -m build --wheel` and install that wheel. Runtime use

{stackos_connectors-0.1.0 → stackos_connectors-0.2.0}/README.md

@@ -4,8 +4,10 @@ A Python library of named provider connectors. A caller supplies a connector,
 action, input data and resolved authentication. The library maps that action to
 the provider protocol and returns provider output, metadata and file descriptors.
 
-The consumer owns credential storage and refresh, authorization, persistent state,
-workflow decisions and audit. Provider implementations use plain contracts and
+The consumer owns credential storage, when to authorize or refresh, persistent
+state, workflow decisions and audit. Explicit package functions implement provider
+authorization URLs, token grants, probes and signature checks. They never start
+authorization, refresh tokens or persist state implicitly. Provider implementations use plain contracts and
 can accept caller-owned HTTP clients, rate buckets and native protocol sessions.
 
 Each integration is grouped under `src/stackos_connectors/connectors/`:
@@ -55,6 +57,74 @@ execution; existing names cannot be replaced.
 `CallOptions.timeout=None` preserves each provider's default. A numeric timeout
 overrides that default. A supplied HTTP client remains caller-owned.
 
+## Explicit authentication
+
+`get_auth_contract(connector, method=..., config=...)` reads immutable provider
+facts from the bundled catalog. `build_authorization_request` formats a consent
+URL using the caller's redirect URI, state and optional PKCE challenge. The caller
+opens that URL, handles the callback and checks its state. `request_token` performs
+one requested `authorization_code`, `refresh_token`, `client_credentials` or
+`jwt_bearer` grant, where the selected method declares support. Meta's declared
+second token exchange is part of that explicit request.
+
+```python
+from stackos_connectors import ConnectorAuth, request_token
+
+token = await request_token(
+    "google-search-console",
+    auth=ConnectorAuth(
+        method="oauth2_authorization_code",
+        fields={"client_id": client_id, "client_secret": client_secret},
+    ),
+    grant_type="authorization_code",
+    code=validated_callback_code,
+    redirect_uri=registered_redirect_uri,
+    code_verifier=stored_pkce_verifier,
+    http=caller_http,
+)
+```
+
+Grant calls accept resolved application/key fields; action and probe calls accept
+the method's resolved execution fields, usually an access token. The catalog's
+`setup` and `protocol` describe acquisition separately from `fields_schema` and
+`config_schema`. Manual token methods retain their declared refresh compatibility;
+the library does not infer an auth method from token shape.
+
+`TokenResult` holds sensitive in-process values. An absent `refresh_token` means
+the response did not rotate it. `scopes_present=False` distinguishes omitted
+scope evidence from an explicitly empty grant. For a successful Google JWT grant,
+the immutable contract supplies the signed request's scopes; the consumer can
+apply the reviewed omission rule without changing the token response's provenance.
+The caller decides how to preserve prior evidence, enforce permissions and store
+results. `OAuthTokenError` exposes bounded categories/status and repair facts,
+without raw provider response bodies. Repr suppression is not a storage policy.
+
+`probe_credentials(connector, auth=..., options=..., context=...)` explicitly
+tests a resolved credential through a fixed provider binding. It returns safe
+provider facts and optional `AuthProbeEvidence`; it does not establish application
+readiness or permissions. `project_probe_config` projects portable config and
+retains supported legacy probe aliases. The caller chooses the IMAP native mailbox
+through `CallOptions(provider_context={"mailbox": ...})`. Google Ads/Workspace
+service-account probes only report resolved-token presence and unverified resource
+access; they make no HTTP call or new-grant claim.
+
+Google JWT validation/signing is shared across the five declared service-account
+methods. Credentials never come from ambient identity or key-supplied endpoints.
+Provider details live in `connectors/<provider>/docs/auth.md` and the catalog.
+Google Indexing retains its existing resolved-token action/probe contract; this
+release adds no Indexing JWT acquisition method.
+
+Provider-local pure helpers cover Telegram authorization request/challenge/state
+translation (`connectors.telegram.auth`), Slack v0 HMAC verification
+(`connectors.slack_bot.auth.verify_signature_v0`) and HubSpot v3 HMAC verification
+(`connectors.hubspot.signature.verify_signature_v3`). Callers own native sessions,
+encrypted custody, challenge expiry, ingress routing, trusted canonical URI,
+timestamp/replay checks and policy. HubSpot v2 verification is not implemented.
+
+No library call to discovery, probe or action execution starts an authorization
+flow, refreshes a token, opens a native session, stores credentials or selects
+readiness. Remote token revocation is not part of this API.
+
 For file-producing actions, pass `CallOptions(output_dir=Path(...))` and consume
 the plain descriptors in `result.files`. The library does not create application
 artifacts or public download URLs. Telegram actions require an already authorized
@@ -102,10 +172,10 @@ Python 3.12 or newer is required. Source:
 Published releases can be installed with:
 
 ```bash
-python -m pip install stackos-connectors==0.1.0
+python -m pip install stackos-connectors==0.2.0
 ```
 
-Or add `stackos-connectors==0.1.0` to your Python dependency requirements.
+Or add `stackos-connectors==0.2.0` to your Python dependency requirements.
 
 Install from a local checkout with `pip install /path/to/StackOSConnectors`, or
 build a wheel with `python -m build --wheel` and install that wheel. Runtime use

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

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

{stackos_connectors-0.1.0 → stackos_connectors-0.2.0}/src/stackos_connectors/__init__.py

@@ -4,6 +4,15 @@ from collections.abc import Mapping
 from functools import lru_cache
 from typing import Any
 
+from .auth import (
+    AuthorizationRequest,
+    OAuthProviderContract,
+    OAuthTokenError,
+    TokenResult,
+    build_authorization_request,
+    get_auth_contract,
+    request_token,
+)
 from .contracts import (
     ActionDefinition,
     AuthMethodDefinition,
@@ -18,6 +27,12 @@ from .contracts import (
     ValidationIssue,
 )
 from .errors import ConnectorError, IntegrationDownError, RateLimitedError, ValidationError
+from .probe import (
+    AuthMethodProbeContext,
+    AuthProbeEvidence,
+    probe_credentials,
+    project_probe_config,
+)
 from .registry import ConnectorClient, ConnectorRegistry
 
 
@@ -74,6 +89,9 @@ def describe(connector: str, action: str | None = None) -> dict[str, Any]:
 __all__ = [
     "ActionDefinition",
     "AuthMethodDefinition",
+    "AuthMethodProbeContext",
+    "AuthProbeEvidence",
+    "AuthorizationRequest",
     "CallOptions",
     "Connector",
     "ConnectorAuth",
@@ -85,15 +103,23 @@ __all__ = [
     "ConnectorResult",
     "IntegrationDownError",
     "NativeSession",
+    "OAuthProviderContract",
+    "OAuthTokenError",
     "RateLimitedError",
     "RateLimiter",
+    "TokenResult",
     "ValidationError",
     "ValidationIssue",
+    "build_authorization_request",
     "describe",
     "estimate_cost",
     "execute",
+    "get_auth_contract",
     "get_default_client",
     "list_connectors",
+    "probe_credentials",
+    "project_probe_config",
+    "request_token",
     "validate",
     "validate_data",
 ]

stackos_connectors-0.2.0/src/stackos_connectors/auth.py

@@ -0,0 +1,245 @@
+"""Explicit provider authentication protocols; the caller owns every lifecycle decision.
+
+These functions never store credentials, launch consent, choose when to renew, or
+enforce application readiness. Token results are sensitive in-process values.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field, fields, replace
+from importlib import import_module
+from typing import Any, Literal
+from urllib.parse import urlencode
+
+import httpx
+
+from .contracts import ConnectorAuth, freeze, thaw
+
+
+class OAuthTokenError(ValueError):
+    """Allowlisted protocol diagnostics, never provider bodies or request objects."""
+
+    def __init__(
+        self,
+        detail: str,
+        *,
+        provider_key: str | None = None,
+        category: str = "invalid_input",
+        retryable: bool = False,
+        repair_required: bool = False,
+        status_code: int | None = None,
+        invalid_fields: Sequence[str] = (),
+    ) -> None:
+        super().__init__(detail)
+        self.provider_key = provider_key
+        self.category = category
+        self.retryable = retryable
+        self.repair_required = repair_required
+        self.status_code = status_code
+        self.invalid_fields = tuple(invalid_fields)
+
+
+@dataclass(frozen=True)
+class OAuthProviderContract:
+    provider_key: str
+    flow: Literal["authorization_code", "client_credentials", "jwt_bearer"]
+    token_endpoint: str
+    authorization_endpoint: str | None = None
+    include_response_type: bool = True
+    scopes: tuple[str, ...] = ()
+    scope_separator: str = " "
+    optional_scope_parameter: str | None = None
+    client_auth_style: Literal["body", "basic"] = "body"
+    pkce_mode: Literal["required", "supported", "unavailable"] = "unavailable"
+    authorization_params: tuple[tuple[str, str], ...] = ()
+    token_params: tuple[tuple[str, str], ...] = ()
+    response_metadata_fields: tuple[str, ...] = ()
+    response_scope_fields: tuple[str, ...] = ("scope",)
+    response_account_id_field: str | None = "id"
+    authorization_code_response_requirements: tuple[str, ...] = ()
+    refresh_token_response_requirements: tuple[str, ...] = ()
+    required_token_type: str | None = None
+    required_scope_subset: tuple[str, ...] = ()
+    hook: str | None = None
+    delegated_subject: str | None = field(default=None, repr=False)
+    grant_types: tuple[str, ...] = ()
+    response_config_fields: tuple[tuple[str, str, str], ...] = ()
+    optional_scope_bundles: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for descriptor in fields(self):
+            value = getattr(self, descriptor.name)
+            if isinstance(value, Mapping | list | tuple):
+                object.__setattr__(self, descriptor.name, freeze(value))
+
+
+@dataclass(frozen=True)
+class AuthorizationRequest:
+    url: str = field(repr=False)
+    required_scopes: tuple[str, ...] = ()
+    optional_scopes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class TokenResult:
+    access_token: str = field(repr=False)
+    refresh_token: str | None = field(default=None, repr=False)
+    expires_in: int | float | None = None
+    token_type: str | None = field(default=None, repr=False)
+    scopes: tuple[str, ...] | None = field(default=None, repr=False)
+    scopes_present: bool = False
+    account_id: str | None = field(default=None, repr=False)
+    metadata: Mapping[str, Any] = field(default_factory=dict, repr=False)
+    config_updates: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "metadata", freeze(self.metadata))
+        object.__setattr__(self, "config_updates", freeze(self.config_updates))
+        if self.scopes is not None:
+            object.__setattr__(self, "scopes", tuple(self.scopes))
+
+
+def _declaration(connector: str, method: str) -> tuple[Mapping, Mapping]:
+    from . import get_default_client
+
+    metadata = get_default_client().registry.connector_metadata.get(connector)
+    if metadata is None:
+        raise OAuthTokenError("connector has no supported authentication protocol")
+    declaration = next(
+        (item for item in metadata.get("auth_methods", ()) if item["key"] == method),
+        None,
+    )
+    if declaration is None or "protocol" not in declaration or "auth_protocol" not in metadata:
+        raise OAuthTokenError(
+            "auth method has no supported authentication protocol", provider_key=connector
+        )
+    return metadata, declaration
+
+
+def get_auth_contract(
+    connector: str,
+    *,
+    method: str,
+    config: Mapping[str, Any] | None = None,
+) -> OAuthProviderContract:
+    """Read trusted provider facts; configuration cannot replace protocol endpoints."""
+    metadata, declaration = _declaration(connector, method)
+    data = thaw(metadata["auth_protocol"])
+    method_data = thaw(declaration["protocol"])
+    direct_scopes = method_data.pop("direct_scopes", None)
+    data.update(method_data)
+    contract = OAuthProviderContract(provider_key=connector, **data)
+    if contract.flow == "jwt_bearer":
+        from .shared.google.service_account import delegated_subject
+
+        subject = delegated_subject(connector, (config or {}).get("delegated_subject"))
+        contract = replace(contract, delegated_subject=subject)
+        if subject is None and direct_scopes is not None:
+            contract = replace(contract, scopes=tuple(direct_scopes))
+    if binding := metadata.get("auth_implementation"):
+        module_name, function_name = binding.split(":", 1)
+        contract = getattr(import_module(module_name), function_name)(contract, config or {})
+    return contract
+
+
+def build_authorization_request(
+    connector: str,
+    *,
+    auth: ConnectorAuth,
+    redirect_uri: str,
+    state: str,
+    code_challenge: str | None = None,
+    optional_scopes: Sequence[str] = (),
+) -> AuthorizationRequest:
+    """Format one consent URL using caller-generated state and PKCE challenge."""
+    contract = get_auth_contract(connector, method=auth.method, config=auth.config)
+    if "authorization_code" not in contract.grant_types or not contract.authorization_endpoint:
+        raise OAuthTokenError(
+            "auth method does not support authorization-code consent", provider_key=connector
+        )
+    client_id = auth.fields.get("client_id")
+    if not isinstance(client_id, str) or not client_id.strip():
+        raise OAuthTokenError("OAuth application id is missing", provider_key=connector)
+    if (
+        not isinstance(redirect_uri, str)
+        or not redirect_uri
+        or not isinstance(state, str)
+        or not state
+    ):
+        raise OAuthTokenError("callback URI and state are required", provider_key=connector)
+    if code_challenge is not None and (not isinstance(code_challenge, str) or not code_challenge):
+        raise OAuthTokenError("PKCE challenge is invalid", provider_key=connector)
+    if contract.pkce_mode == "required" and not code_challenge:
+        raise OAuthTokenError("provider requires PKCE S256", provider_key=connector)
+    if contract.pkce_mode == "unavailable" and code_challenge is not None:
+        raise OAuthTokenError("provider does not support PKCE", provider_key=connector)
+    allowed_optional = {
+        scope
+        for bundle in contract.optional_scope_bundles.values()
+        for scope in bundle.get("optional_scopes", ())
+    }
+    if isinstance(optional_scopes, str) or any(
+        not isinstance(s, str) or s not in allowed_optional for s in optional_scopes
+    ):
+        raise OAuthTokenError("optional scopes must be provider-declared", provider_key=connector)
+    optional = tuple(dict.fromkeys(optional_scopes))
+    if optional and not contract.optional_scope_parameter:
+        raise OAuthTokenError(
+            "provider does not support optional consent scopes", provider_key=connector
+        )
+    query = {"client_id": client_id.strip(), "redirect_uri": redirect_uri, "state": state}
+    if contract.include_response_type:
+        query["response_type"] = "code"
+    if contract.scopes:
+        query["scope"] = contract.scope_separator.join(contract.scopes)
+    if optional and contract.optional_scope_parameter:
+        query[contract.optional_scope_parameter] = contract.scope_separator.join(optional)
+    query.update(contract.authorization_params)
+    if code_challenge:
+        query.update(code_challenge=code_challenge, code_challenge_method="S256")
+    return AuthorizationRequest(
+        f"{contract.authorization_endpoint}?{urlencode(query)}",
+        contract.scopes,
+        optional,
+    )
+
+
+async def request_token(
+    connector: str,
+    *,
+    auth: ConnectorAuth,
+    grant_type: Literal["authorization_code", "refresh_token", "client_credentials", "jwt_bearer"],
+    code: str | None = None,
+    redirect_uri: str | None = None,
+    code_verifier: str | None = None,
+    refresh_token: str | None = None,
+    http: httpx.AsyncClient | None = None,
+    timeout: float = 30,
+) -> TokenResult:
+    """Perform exactly one explicit grant (including a declared provider second exchange)."""
+    from .shared.oauth import request_token as perform
+
+    contract = get_auth_contract(connector, method=auth.method, config=auth.config)
+    return await perform(
+        contract=contract,
+        auth=auth,
+        grant_type=grant_type,
+        code=code,
+        redirect_uri=redirect_uri,
+        code_verifier=code_verifier,
+        refresh_token=refresh_token,
+        http=http,
+        timeout=timeout,
+    )
+
+
+__all__ = [
+    "AuthorizationRequest",
+    "OAuthProviderContract",
+    "OAuthTokenError",
+    "TokenResult",
+    "build_authorization_request",
+    "get_auth_contract",
+    "request_token",
+]