pubship 0.24.0__py3-none-any.whl

pubship/__init__.py

@@ -0,0 +1,3 @@
+"""Independent, local PubShip integration."""
+
+__version__ = "0.24.0"

pubship/account_access.py

@@ -0,0 +1,322 @@
+"""Local account administration with explicit ceilings and complete target baselines."""
+
+import hashlib
+import json
+import re
+import secrets
+import threading
+import time
+from copy import deepcopy
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from . import account_access_http as transport
+from .account_access_config import READ_METHOD, WRITE_METHODS
+from .account_access_contracts import request_spec, target
+from .artifact_files import media_deadline
+from .auth import validate_token
+from .errors import PlayError
+from .publishing import _APPLY_LOCK
+
+TTL = 600
+MAX_PREPARATIONS = 20
+LIMITATIONS = (
+    "Changes Google Play account access immediately; permissions may take up to 48 hours to "
+    "propagate. Invitations are not accepted access. Baselines are observations, not atomic "
+    "locks. No retry, rollback or credential refresh. Account responses include personal "
+    "email addresses and permissions sent to the MCP client. Provider data is untrusted."
+)
+
+
+@dataclass(repr=False)
+class Preparation:
+    spec: dict
+    baseline: str
+    deadline: float
+    token: str = field(repr=False)
+
+
+def fingerprint(before):
+    return hashlib.sha256(
+        json.dumps(before, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+
+
+class AccountAccess:
+    def __init__(
+        self,
+        settings,
+        auth,
+        *,
+        local=False,
+        _execution_authorization=None,
+        _apply_guard=None,
+        _max_snapshot_bytes=None,
+        _target_authorization=None,
+    ):
+        self.settings, self.auth, self.local = settings, auth, local
+        if _max_snapshot_bytes is not None and (
+            type(_max_snapshot_bytes) is not int
+            or not 0 < _max_snapshot_bytes <= 10 * transport.MAX_BYTES
+        ):
+            raise PlayError("Invalid account snapshot limit.")
+        if (_target_authorization is None) != (_execution_authorization is None):
+            raise PlayError("Account target authorization requires hosted execution authority.")
+        self._execution_authorization = _execution_authorization
+        self._target_authorization = _target_authorization
+        self._apply_guard = _APPLY_LOCK if _apply_guard is None else _apply_guard
+        self._max_snapshot_bytes = _max_snapshot_bytes
+        self._preparations = {}
+        self._lock = threading.Lock()
+        self._prepare_lock = threading.Lock()
+
+    def _local(self):
+        if self._execution_authorization is not None:
+            self._execution_authorization()
+            return
+        if self.local is not True:
+            raise PlayError("Account administration requires explicitly local services.")
+
+    def _authorize(self, spec, *, mutation=False):
+        self._local()
+        if self._target_authorization is not None:
+            self._target_authorization(deepcopy(spec), None)
+            self._local()
+            return
+        self.settings.require(spec["developer"], spec["method"], spec["user"], spec["app"])
+        if mutation:
+            self.settings.require(spec["developer"], READ_METHOD)
+            body = spec["body"] or {}
+            self.settings.permissions(
+                body.get("developerAccountPermissions", []), body.get("appLevelPermissions", [])
+            )
+
+    def _preflight(self, spec, before):
+        if before is not None and before.get("partial", False):
+            raise PlayError(
+                "Partial or owner account users cannot be safely managed via this tool."
+            )
+        existing = before
+        if spec["grant"]:
+            if before is None:
+                raise PlayError("Account grant target user does not exist.")
+            existing = next(
+                (g for g in before.get("grants", []) if g["name"] == spec["resource"]), None
+            )
+        if spec["operation"] == "create" and existing is not None:
+            raise PlayError("Account target already exists; create is not an update.")
+        if spec["operation"] != "create" and existing is None:
+            raise PlayError("Account target is absent; no mutation attempted.")
+        if self._target_authorization is not None:
+            self._target_authorization(deepcopy(spec), deepcopy(before))
+            self._local()
+            return
+        if existing is not None:
+            self.settings.permissions(
+                existing.get("developerAccountPermissions", []),
+                existing.get("appLevelPermissions", []),
+            )
+        if not spec["grant"] and spec["operation"] == "delete":
+            # Removing a user also removes every app grant; all must be within scope.
+            for grant in before.get("grants", []):
+                developer, user, app = target(grant["name"], grant=True)
+                self.settings.require(developer, spec["method"], user, app)
+                self.settings.permissions(app_permissions=grant.get("appLevelPermissions", []))
+
+    def _current(self, deadline):
+        self._local()
+        transport.fresh(deadline)
+
+    def _target_current(self, spec, deadline, before=None):
+        self._current(deadline)
+        if self._target_authorization is not None:
+            self._target_authorization(deepcopy(spec), deepcopy(before))
+            self._current(deadline)
+
+    def _options(self, deadline, spec, *, observation=False, before=None):
+        if self._execution_authorization is None and self._max_snapshot_bytes is None:
+            return {}
+        options = {"_execution_authorization": lambda: self._target_current(spec, deadline, before)}
+        if observation:
+            options["_max_snapshot_bytes"] = self._max_snapshot_bytes
+        else:
+            options["deadline"] = deadline
+            options["_max_bytes"] = min(
+                self._max_snapshot_bytes or transport.MAX_BYTES, transport.MAX_BYTES
+            )
+        return options
+
+    def _prune(self):
+        for key, preparation in list(self._preparations.items()):
+            if time.monotonic() >= preparation.deadline:
+                self._clear(self._preparations.pop(key))
+
+    @staticmethod
+    def _clear(preparation):
+        preparation.token = ""
+        preparation.spec = {}
+        preparation.baseline = ""
+
+    def _dispose(self, operation_id):
+        with self._prepare_lock, self._lock:
+            self._prune()
+            preparation = self._preparations.pop(operation_id, None)
+            if preparation is not None:
+                self._clear(preparation)
+        return "disposed"
+
+    def close(self):
+        with self._prepare_lock, self._lock:
+            for preparation in self._preparations.values():
+                self._clear(preparation)
+            self._preparations.clear()
+
+    def _retained_metadata(self, operation_id):
+        with self._lock:
+            p = self._preparations[operation_id]
+            return {
+                "spec": deepcopy(p.spec),
+                "baseline": p.baseline,
+                "deadline": p.deadline,
+                "credential_bytes": len(p.token.encode()),
+            }
+
+    def read(self, method, parameters):
+        if method != READ_METHOD:
+            raise PlayError("Only users.list is an account read method.")
+        spec = request_spec(method, parameters)
+        self._authorize(spec)
+        deadline = media_deadline(time.monotonic() + TTL, self._execution_authorization)
+        token = validate_token(self.auth.token("publisher"))
+        self._target_current(spec, deadline)
+        response = transport.request(spec, token, **self._options(deadline, spec))
+        transport.validate_response(spec, response)
+        self._current(deadline)
+        return {
+            "method": method,
+            "response": response,
+            "data_scope": "account_personal_data",
+            "fetched_at": datetime.now(UTC).isoformat(),
+            "note": "One provider page; preserve nextPageToken. " + LIMITATIONS,
+        }
+
+    def prepare(self, method, parameters, body=None, acknowledge_access_effects=False):
+        if not isinstance(method, str) or method not in WRITE_METHODS:
+            raise PlayError("Method is not a supported account mutation.")
+        spec = request_spec(method, parameters, body)
+        self._authorize(spec, mutation=True)
+        if acknowledge_access_effects is not True:
+            raise PlayError("acknowledge_access_effects must be true. " + LIMITATIONS)
+        with self._prepare_lock:
+            now = time.monotonic()
+            with self._lock:
+                self._prune()
+                if len(self._preparations) >= MAX_PREPARATIONS:
+                    raise PlayError(
+                        "Account preparation capacity reached; apply or wait for expiry."
+                    )
+            deadline = media_deadline(now + TTL, self._execution_authorization)
+            token = validate_token(self.auth.token("publisher"))
+            self._target_current(spec, deadline)
+            before = transport.observe(
+                spec, token, deadline, **self._options(deadline, spec, observation=True)
+            )
+            self._preflight(spec, before)
+            self._current(deadline)
+            operation_id = "account_" + secrets.token_urlsafe(32)
+            with self._lock:
+                while operation_id in self._preparations:
+                    operation_id = "account_" + secrets.token_urlsafe(32)
+                self._preparations[operation_id] = Preparation(
+                    spec, fingerprint(before), deadline, token
+                )
+        return {
+            "operation_id": operation_id,
+            "method": method,
+            "before": deepcopy(before),
+            "proposed_request": deepcopy(spec),
+            "executed": False,
+            "effects": LIMITATIONS,
+            "access_lifetime": (
+                (spec["body"] or {}).get("expirationTime", "indefinite")
+                if not spec["grant"]
+                and (
+                    spec["operation"] == "create"
+                    or "expirationTime" in spec["parameters"].get("updateMask", "").split(",")
+                )
+                else "unchanged"
+            ),
+            "expires_at": datetime.fromtimestamp(
+                time.time() + deadline - time.monotonic(), UTC
+            ).isoformat(),
+            "note": "Repeat operation_id exactly after reviewing all effects. Confirmation is not proof of human approval. Single use within ten minutes; original credential retained privately; lost on restart.",
+        }
+
+    def apply(self, operation_id, confirmation):
+        self._local()
+        if (
+            not isinstance(operation_id, str)
+            or not re.fullmatch(r"account_[A-Za-z0-9_-]{43}", operation_id)
+            or confirmation != operation_id
+        ):
+            raise PlayError("Confirmation must exactly repeat the account operation_id.")
+        with self._lock:
+            p = self._preparations.pop(operation_id, None)
+            self._prune()
+        if p is None:
+            raise PlayError("Unknown, consumed or lost account preparation.")
+        acquired = False
+        try:
+            acquired = self._apply_guard.acquire(blocking=False)
+            if not acquired:
+                raise PlayError(
+                    "Another apply is in progress; this account operation ID is consumed."
+                )
+            spec = request_spec(p.spec["method"], p.spec["parameters"], p.spec["body"])
+            self._authorize(spec, mutation=True)
+            self._current(p.deadline)
+            before = transport.observe(
+                spec, p.token, p.deadline, **self._options(p.deadline, spec, observation=True)
+            )
+            self._preflight(spec, before)
+            if fingerprint(before) != p.baseline:
+                raise PlayError("Account baseline changed; no mutation attempted. Prepare again.")
+            self._current(p.deadline)
+            mutation = transport.request(
+                spec, p.token, **self._options(p.deadline, spec, before=before)
+            )
+            try:
+                transport.validate_response(spec, mutation)
+            except PlayError:
+                raise PlayError(transport.UNKNOWN_OUTCOME) from None
+            result = {
+                "operation_id": operation_id,
+                "method": spec["method"],
+                "executed": True,
+                "mutation_succeeded": True,
+                "mutation_response": mutation,
+                "permission_propagation_verified": False,
+                "note": LIMITATIONS,
+            }
+            try:
+                self._current(p.deadline)
+                after = transport.observe(
+                    spec, p.token, p.deadline, **self._options(p.deadline, spec, observation=True)
+                )
+                self._current(p.deadline)
+            except Exception:
+                result.update(
+                    readback_succeeded=False,
+                    observation_error="Mutation succeeded but account readback failed; reconcile before preparing again.",
+                )
+            else:
+                result.update(
+                    readback_succeeded=True,
+                    after=after,
+                    observation_note="Observed resource only; effective access and permission propagation are not verified.",
+                )
+            return result
+        finally:
+            self._clear(p)
+            if acquired:
+                self._apply_guard.release()

pubship/account_access_config.py

@@ -0,0 +1,99 @@
+"""Independent local account administration scopes and permission ceilings."""
+
+import os
+import re
+from dataclasses import dataclass
+
+from .config import PACKAGE
+from .contracts import definitions
+from .errors import PlayError
+
+PREFIX = "androidpublisher."
+READ_METHOD = PREFIX + "users.list"
+WRITE_METHODS = frozenset(
+    PREFIX + family + "." + action
+    for family in ("users", "grants")
+    for action in ("create", "patch", "delete")
+)
+METHODS = WRITE_METHODS | {READ_METHOD}
+DEVELOPER = re.compile(r"[0-9]{1,30}")
+EMAIL = re.compile(r"[A-Za-z0-9.!#$&'*+=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?")
+APP_ID = re.compile(r"[0-9]{1,30}")
+
+
+def valid_email(value):
+    return isinstance(value, str) and len(value) <= 254 and EMAIL.fullmatch(value) is not None
+
+
+def valid_app(value):
+    return (
+        isinstance(value, str)
+        and len(value) <= 255
+        and (PACKAGE.fullmatch(value) is not None or APP_ID.fullmatch(value) is not None)
+    )
+
+
+def permission_values(resource, field):
+    values = definitions()["androidpublisher"]["schemas"][resource]["properties"][field]["items"]
+    return frozenset(
+        value
+        for value, deprecated in zip(values["enum"], values["enumDeprecated"], strict=True)
+        if not deprecated and not value.endswith("_UNSPECIFIED")
+    )
+
+
+@dataclass(frozen=True)
+class AccountAccessSettings:
+    developers: frozenset[str] = frozenset()
+    methods: frozenset[str] = frozenset()
+    users: frozenset[str] = frozenset()
+    apps: frozenset[str] = frozenset()
+    developer_permissions: frozenset[str] = frozenset()
+    app_permissions: frozenset[str] = frozenset()
+
+    def __post_init__(self):
+        checks = (
+            (self.developers, lambda v: isinstance(v, str) and DEVELOPER.fullmatch(v)),
+            (self.methods, lambda v: v in METHODS),
+            (self.users, valid_email),
+            (self.apps, valid_app),
+            (
+                self.developer_permissions,
+                lambda v: v in permission_values("User", "developerAccountPermissions"),
+            ),
+            (
+                self.app_permissions,
+                lambda v: v in permission_values("Grant", "appLevelPermissions"),
+            ),
+        )
+        for values, predicate in checks:
+            if not isinstance(values, frozenset) or any(not predicate(v) for v in values):
+                raise PlayError("Invalid exact account access scope or permission ceiling.")
+
+    @classmethod
+    def from_env(cls, base_settings=None):
+        # Deliberately independent of package, publishing, ADC and hosted settings.
+        def values(suffix):
+            raw = os.environ.get("GOOGLE_PLAY_ACCOUNT_ACCESS_" + suffix, "")
+            if not raw:
+                return frozenset()
+            parts = raw.split(",")
+            if any(not part.strip() for part in parts):
+                raise PlayError("Account access scopes require nonempty comma-separated values.")
+            return frozenset(part.strip() for part in parts)
+
+        return cls(**{name: values(name.upper()) for name in cls.__dataclass_fields__})
+
+    def require(self, developer, method, user=None, app=None):
+        if developer not in self.developers or method not in self.methods:
+            raise PlayError("Account developer and exact method require explicit local grants.")
+        if user is not None and user not in self.users:
+            raise PlayError("Account target user requires an explicit local grant.")
+        if app is not None and app not in self.apps:
+            raise PlayError("Account target app requires an explicit local grant.")
+
+    def permissions(self, developer_permissions=(), app_permissions=()):
+        if not set(developer_permissions).issubset(self.developer_permissions) or not set(
+            app_permissions
+        ).issubset(self.app_permissions):
+            raise PlayError("Account operation exceeds the configured permission ceiling.")

pubship/account_access_contracts.py

@@ -0,0 +1,151 @@
+"""Strict users/grants contracts supplementing the pinned provider schema."""
+
+import re
+from copy import deepcopy
+from datetime import UTC, datetime
+from urllib.parse import quote, urlencode
+
+from .account_access_config import (
+    DEVELOPER,
+    METHODS,
+    READ_METHOD,
+    permission_values,
+    valid_app,
+    valid_email,
+)
+from .contracts import methods, validate_request
+from .errors import PlayError
+
+
+def _fail():
+    raise PlayError("Invalid account access target, fields or permissions.")
+
+
+def target(name, grant=False, parent=False):
+    if not isinstance(name, str):
+        _fail()
+    parts = name.split("/")
+    length = 2 if parent else 6 if grant else 4
+    if len(parts) != length or parts[0] != "developers" or not DEVELOPER.fullmatch(parts[1]):
+        _fail()
+    if length > 2 and (parts[2] != "users" or not valid_email(parts[3])):
+        _fail()
+    if grant and (parts[4] != "grants" or not valid_app(parts[5])):
+        _fail()
+    return parts[1], parts[3] if length > 2 else None, parts[5] if grant else None
+
+
+def _permissions(body, field, resource):
+    if field not in body:
+        return
+    values = body[field]
+    if (
+        not isinstance(values, list)
+        or len(values) != len(set(values))
+        or not set(values).issubset(permission_values(resource, field))
+    ):
+        _fail()
+
+
+def request_spec(method, parameters, body=None):
+    if not isinstance(method, str) or method not in METHODS:
+        _fail()
+    validate_request(method, parameters, body)
+    parameters, body = deepcopy(parameters), deepcopy(body)
+    operation = method.rsplit(".", 1)[1]
+    grant = ".grants." in method
+    if method == READ_METHOD:
+        developer, user, app = target(parameters["parent"], parent=True)
+        if "pageSize" in parameters and (
+            type(parameters["pageSize"]) is not int or not 1 <= parameters["pageSize"] <= 1000
+        ):
+            raise PlayError("Account reads support bounded pageSize values from 1 to 1000.")
+        if "pageToken" in parameters and (
+            not isinstance(parameters["pageToken"], str)
+            or not 1 <= len(parameters["pageToken"]) <= 8192
+            or not parameters["pageToken"].isprintable()
+        ):
+            _fail()
+        resource = None
+    elif operation == "create":
+        developer, user, _ = target(parameters["parent"], parent=not grant)
+        resource = body.get("name")
+        bd, bu, app = target(resource, grant=grant)
+        if bd != developer or grant and bu != user:
+            _fail()
+        user = bu
+    else:
+        resource = parameters["name"]
+        developer, user, app = target(resource, grant=grant)
+    if body is not None:
+        allowed = (
+            {"name", "packageName", "appLevelPermissions"}
+            if grant
+            else {"name", "email", "expirationTime", "developerAccountPermissions"}
+        )
+        if not set(body).issubset(allowed) or body.get("name", resource) != resource:
+            _fail()
+        if grant:
+            expected = "" if app.isdigit() else app
+            if body.get("packageName", expected) != expected:
+                _fail()
+            _permissions(body, "appLevelPermissions", "Grant")
+        else:
+            if body.get("email", user) != user:
+                _fail()
+            _permissions(body, "developerAccountPermissions", "User")
+            if "expirationTime" in body:
+                stamp = body["expirationTime"]
+                if not isinstance(stamp, str) or not re.fullmatch(
+                    r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,9})?(?:Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])",
+                    stamp,
+                ):
+                    _fail()
+                try:
+                    parsed = datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+                except ValueError:
+                    _fail()
+                if parsed <= datetime.now(UTC):
+                    raise PlayError("Account access expiration must be in the future.")
+        if operation == "create":
+            if not grant and body.get("email") != user:
+                _fail()
+        if operation == "patch":
+            mutable = (
+                {"appLevelPermissions"}
+                if grant
+                else {"expirationTime", "developerAccountPermissions"}
+            )
+            mask = parameters.get("updateMask")
+            if not isinstance(mask, str):
+                raise PlayError("Account patches require an explicit supported updateMask.")
+            fields = mask.split(",")
+            if not fields or len(set(fields)) != len(fields) or not set(fields).issubset(mutable):
+                _fail()
+            if not (set(body) - {"name", "email", "packageName"}).issubset(fields):
+                _fail()
+            # A mask with an omitted value deliberately resets that field.
+    definition = methods()[method]
+    path = definition["path"]
+    query = {}
+    for key, value in parameters.items():
+        if definition["parameters"][key]["location"] == "path":
+            encoded = "/".join(quote(p, safe="") for p in value.split("/"))
+            path = path.replace("{+" + key + "}", encoded)
+        else:
+            query[key] = value
+    return {
+        "method": method,
+        "http_method": definition["httpMethod"],
+        "url": "https://androidpublisher.googleapis.com/"
+        + path
+        + ("?" + urlencode(query) if query else ""),
+        "parameters": parameters,
+        "body": body,
+        "developer": developer,
+        "user": user,
+        "app": app,
+        "resource": resource,
+        "operation": operation,
+        "grant": grant,
+    }