sfdctrust 0.1.0__py3-none-any.whl

sfdctrust/_constants.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._constants
+:Synopsis:          Package identity and My Trust Center API defaults
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6)
+:Modified Date:     01 Nov 2026
+"""
+
+from typing import Final
+
+PACKAGE_NAME: Final[str] = 'sfdctrust'
+DEFAULT_BASE_URL: Final[str] = 'https://api.salesforce.com/platform/mytrust/v1'
+DEFAULT_LOCALE: Final[str] = 'en-US'

sfdctrust/_exceptions.py

@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._exceptions
+:Synopsis:          Exception classes that are utilized throughout the package
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+__all__ = [
+    'TrustCenterError',
+    'ConfigurationError',
+    'NetworkError',
+    'RequestTimeoutError',
+    'APIStatusError',
+    'AuthenticationError',
+    'RateLimitError',
+    'NotFoundError',
+    'MalformedResponseError',
+    'PaginationError',
+    'PATRefreshPendingError',
+    'PATRefreshAmbiguousError',
+    'PATPersistenceError',
+    'PATProbeResult',
+]
+
+
+class TrustCenterError(Exception):
+    """Base class for sfdctrust exceptions."""
+
+
+class ConfigurationError(TrustCenterError):
+    """Invalid SDK configuration; messages must be SDK-authored and secret-free."""
+
+
+class NetworkError(TrustCenterError):
+    """A request could not complete because of a network failure.
+
+    Construct with a safe SDK-authored message, never an underlying exception's
+    text, request, URL, headers, or response body.
+    """
+
+
+class RequestTimeoutError(NetworkError):
+    """A request exceeded its configured timeout."""
+
+
+class APIStatusError(TrustCenterError):
+    """An API request returned an unsuccessful HTTP status.
+
+    Only the status is retained. Raw requests, responses, and server messages
+    are deliberately excluded. Request IDs are deferred until a documented,
+    safe source is verified; no header name is assumed.
+
+    :param status_code: An HTTP error status from 400 through 599.
+    :raises ValueError: If the status is not an integer HTTP error status.
+    """
+
+    def __init__(self, status_code: int) -> None:
+        if type(status_code) is not int or not 400 <= status_code <= 599:
+            raise ValueError('status_code must be an integer from 400 through 599')
+        self.status_code = status_code
+        super().__init__(f'My Trust Center API returned HTTP {status_code}.')
+
+
+class AuthenticationError(APIStatusError):
+    """HTTP 401: the PAT is missing, invalid, revoked, or expired.
+
+    This error does not identify which condition occurred and never triggers
+    PAT refresh or credential replacement.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(401)
+
+
+class RateLimitError(APIStatusError):
+    """HTTP 429, without assuming JSON content or retry-related headers."""
+
+    def __init__(self) -> None:
+        super().__init__(429)
+
+
+class NotFoundError(APIStatusError):
+    """HTTP 404: the resource does not exist or is not authorized."""
+
+    def __init__(self) -> None:
+        super().__init__(404)
+
+
+class MalformedResponseError(TrustCenterError):
+    """A successful response could not be decoded or validated.
+
+    Construct with a safe SDK-authored message, without response content or
+    validation errors that might echo sensitive input.
+    """
+
+
+class PaginationError(TrustCenterError):
+    """A traversal requires another page but reached its limit or repeated a cursor."""
+
+
+class PATProbeResult(StrEnum):
+    """Result of the single read-only check with the old PAT."""
+
+    OLD_PAT_ACCEPTED = 'old_pat_accepted'
+    OLD_PAT_REJECTED = 'old_pat_rejected'
+    INCONCLUSIVE = 'inconclusive'
+
+
+class PATRefreshPendingError(TrustCenterError):
+    """A pending or competing rotation prevents the requested operation."""
+
+
+class PATRefreshAmbiguousError(TrustCenterError):
+    """Salesforce may have rotated the PAT without returning a usable replacement.
+
+    :param probe: Sanitized result of the old PAT check.
+    """
+
+    def __init__(self, probe: PATProbeResult) -> None:
+        self.probe = PATProbeResult(probe)
+        super().__init__(f'PAT refresh outcome is ambiguous. Old PAT probe: {self.probe.value}.')
+
+
+class PATPersistenceError(TrustCenterError):
+    """A required durable PAT store transition could not be confirmed."""

sfdctrust/_pat_refresh.py

@@ -0,0 +1,239 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._pat_refresh
+:Synopsis:          Store coordination and recovery for explicit PAT rotation
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from threading import Lock
+from uuid import UUID, uuid4
+
+from ._auth import PATAuth, _validate_pat
+from ._exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    PATPersistenceError,
+    PATProbeResult,
+    PATRefreshAmbiguousError,
+    PATRefreshPendingError,
+    RateLimitError,
+)
+from ._pat_store import PATStore, PATStoreRecord
+from ._transport import _Transport
+
+_METADATA_FIELDS = frozenset({'secret', 'tokenId', 'label', 'createdAt', 'expiresAt'})
+_DATE_TIME = re.compile(
+    r'[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:[Zz]|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])'
+)
+
+
+@dataclass(frozen=True, slots=True)
+class PATRefreshResult:
+    """Outcome of a durably saved replacement, with no server-supplied values.
+
+    :param metadata_valid: Whether the response metadata matched the documented schema.
+    """
+
+    metadata_valid: bool
+
+
+def _replacement_secret(payload: dict[str, object], old_pat: str) -> str | None:
+    secret = payload.get('secret')
+    if not isinstance(secret, str) or secret == old_pat:
+        return None
+    try:
+        _validate_pat(secret)
+    except ConfigurationError:
+        return None
+    return secret
+
+
+def _validate_metadata(payload: dict[str, object]) -> bool:
+    if payload.keys() != _METADATA_FIELDS or not isinstance(payload['label'], str):
+        return False
+    token_id, created, expires = (payload[key] for key in ('tokenId', 'createdAt', 'expiresAt'))
+    if not isinstance(token_id, str) or not isinstance(created, str) or not isinstance(expires, str):
+        return False
+    if not (_DATE_TIME.fullmatch(created) and _DATE_TIME.fullmatch(expires)):
+        return False
+    try:
+        if str(UUID(token_id)) != token_id.lower():
+            return False
+        datetime.fromisoformat(created.upper())
+        datetime.fromisoformat(expires.upper())
+    except ValueError:
+        return False
+    return True
+
+
+@dataclass(frozen=True, slots=True)
+class _UnconfirmedWrite:
+    revision: UUID
+    attempt: UUID
+    replacement: PATStoreRecord
+    result: PATRefreshResult
+
+
+def _require_ready(record: PATStoreRecord) -> None:
+    if record.pending_attempt is not None:
+        raise PATRefreshPendingError('The PAT store has an unresolved rotation.')
+
+
+def _validate_refresh_days(days: int | None) -> None:
+    if days is not None and (type(days) is not int or not 1 <= days <= 30):
+        raise ConfigurationError('expires_in_days must be an integer from 1 through 30 or None.')
+
+
+def _replacement_write(current: PATStoreRecord, attempt: UUID, payload: dict[str, object] | None) -> _UnconfirmedWrite | None:
+    if payload is None:
+        return None
+    secret = _replacement_secret(payload, current.get_pat())
+    if secret is None:
+        return None
+    replacement = PATStoreRecord(uuid4(), secret)
+    result = PATRefreshResult(metadata_valid=_validate_metadata(payload))
+    return _UnconfirmedWrite(current.revision, attempt, replacement, result)
+
+
+def _probe_error(status: int | None) -> PATRefreshAmbiguousError:
+    probe = {200: PATProbeResult.OLD_PAT_ACCEPTED, 401: PATProbeResult.OLD_PAT_REJECTED}
+    return PATRefreshAmbiguousError(probe.get(status, PATProbeResult.INCONCLUSIVE))
+
+
+def _matches_replacement(current: PATStoreRecord, write: _UnconfirmedWrite) -> bool:
+    return (
+        current.revision == write.replacement.revision
+        and current.pending_attempt is None
+        and current.get_pat() == write.replacement.get_pat()
+    )
+
+
+class _StoredPAT:
+    def __init__(self, store: PATStore) -> None:
+        try:
+            suitable = isinstance(store, PATStore) and callable(store.load) and callable(store.compare_and_swap)
+        except Exception:
+            suitable = False
+        if not suitable:
+            raise ConfigurationError('A versioned PAT store adapter is required.')
+        self._store = store
+        self._operation = Lock()
+        self._unconfirmed: _UnconfirmedWrite | None = None
+        record = self._load()
+        _require_ready(record)
+        self._activate(record)
+
+    def _load(self) -> PATStoreRecord:
+        try:
+            record = self._store.load()
+        except Exception:
+            record = None
+        if type(record) is PATStoreRecord:
+            return record
+        raise ConfigurationError('The PAT store could not supply a valid seeded record.')
+
+    def _swap(
+        self,
+        revision: UUID,
+        attempt: UUID | None,
+        replacement: PATStoreRecord,
+        failure: str,
+    ) -> bool:
+        try:
+            changed = self._store.compare_and_swap(expected_revision=revision, expected_attempt=attempt, replacement=replacement)
+        except Exception:
+            changed = None
+        if type(changed) is bool:
+            return changed
+        raise PATPersistenceError(failure)
+
+    def _activate(self, record: PATStoreRecord) -> None:
+        self._loaded = (record.revision, PATAuth(record.get_pat()))
+
+    def read_auth(self) -> PATAuth:
+        if self._unconfirmed is not None:
+            raise PATPersistenceError('Retry persistence before using this client.')
+        revision, auth = self._loaded
+        record = self._load()
+        _require_ready(record)
+        if record.revision != revision:
+            raise ConfigurationError('The stored PAT changed. Recreate the store-backed client to reload it.')
+        return auth
+
+    def refresh(self, transport: _Transport, days: int | None) -> PATRefreshResult:
+        if not self._operation.acquire(blocking=False):
+            raise PATRefreshPendingError('A PAT operation is already in progress on this client.')
+        try:
+            if self._unconfirmed is not None:
+                raise PATPersistenceError('Retry persistence before refreshing again.')
+            return self._refresh(transport, days)
+        finally:
+            self._operation.release()
+
+    def _refresh(self, transport: _Transport, days: int | None) -> PATRefreshResult:
+        current = self._load()
+        _require_ready(current)
+        old_pat = current.get_pat()
+        auth = PATAuth(old_pat)
+        attempt = uuid4()
+        pending = PATStoreRecord(current.revision, old_pat, attempt)
+        if not self._swap(current.revision, None, pending, 'Could not confirm the pending marker. No refresh was sent.'):
+            raise PATRefreshPendingError('The PAT store changed before refresh. No refresh was sent.')
+
+        status, payload = transport.refresh_once(auth, days)
+        if status in (401, 429):
+            failure = f'Refresh returned HTTP {status}, but the pending marker could not be cleared.'
+            if not self._swap(current.revision, attempt, current, failure):
+                raise PATPersistenceError(failure)
+            if status == 401:
+                raise AuthenticationError()
+            raise RateLimitError()
+
+        write = _replacement_write(current, attempt, payload)
+        if write is None:
+            raise _probe_error(transport.probe_once(auth))
+
+        self._unconfirmed = write
+        return self._commit(write)
+
+    def _commit(self, write: _UnconfirmedWrite) -> PATRefreshResult:
+        failure = 'Could not confirm durable storage of the replacement. Retry persistence on this client.'
+        if not self._swap(write.revision, write.attempt, write.replacement, failure):
+            raise PATPersistenceError(failure)
+        return self._finish(write)
+
+    def _finish(self, write: _UnconfirmedWrite) -> PATRefreshResult:
+        self._activate(write.replacement)
+        self._unconfirmed = None
+        return write.result
+
+    def retry_persistence(self) -> PATRefreshResult:
+        if not self._operation.acquire(blocking=False):
+            raise PATRefreshPendingError('A PAT operation is already in progress on this client.')
+        try:
+            write = self._unconfirmed
+            if write is None:
+                raise ConfigurationError('This client has no replacement awaiting persistence.')
+            return self._reconcile(write)
+        finally:
+            self._operation.release()
+
+    def _reconcile(self, write: _UnconfirmedWrite) -> PATRefreshResult:
+        try:
+            current = self._load()
+        except ConfigurationError:
+            current = None
+        if current is None:
+            raise PATPersistenceError('Could not read the PAT store to confirm the replacement.')
+        if current.revision == write.revision and current.pending_attempt == write.attempt:
+            return self._commit(write)
+        if _matches_replacement(current, write):
+            return self._finish(write)
+        raise PATPersistenceError('The store changed while persistence was unresolved. Reconcile the store before use.')

sfdctrust/_pat_store.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            sfdctrust._pat_store
+:Synopsis:          Versioned credential store contract for explicit PAT rotation
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff (via GPT-6.1 Sol)
+:Modified Date:     04 Nov 2026
+"""
+
+from __future__ import annotations
+
+from dataclasses import InitVar, dataclass, field
+from typing import NoReturn, Protocol, runtime_checkable
+from uuid import UUID
+
+from pydantic import SecretStr
+
+from ._auth import _validate_pat
+from ._exceptions import ConfigurationError
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class PATStoreRecord:
+    """A trusted adapter's snapshot of one PAT lineage.
+
+    :param revision: Unique version of the credential, stable across pending marker changes.
+    :param pat: The PAT without the Bearer prefix.
+    :param pending_attempt: Unique identifier of the unresolved rotation, if any.
+    """
+
+    revision: UUID
+    pat: InitVar[str]
+    pending_attempt: UUID | None = None
+    _secret: SecretStr = field(init=False, repr=False)
+
+    def __post_init__(self, pat: str) -> None:
+        if type(self.revision) is not UUID or (self.pending_attempt is not None and type(self.pending_attempt) is not UUID):
+            raise ConfigurationError('PAT store revisions and attempt identifiers must be UUIDs.')
+        _validate_pat(pat)
+        object.__setattr__(self, '_secret', SecretStr(pat))
+
+    def get_pat(self) -> str:
+        """Return the secret for trusted store adapter I/O only."""
+        return self._secret.get_secret_value()
+
+    def __getstate__(self) -> NoReturn:
+        raise TypeError('PAT store records cannot be serialized.')
+
+
+@runtime_checkable
+class PATStore(Protocol):
+    """Durable, atomic store for one PAT lineage shared by all rotators.
+
+    Implementations must provide strongly consistent reads and durable
+    compare-and-swap across processes. A pending attempt survives loss of a
+    process or lease and is cleared only by a coordinated state transition.
+    """
+
+    def load(self) -> PATStoreRecord | None:
+        """Return the current record, or None for an unseeded lineage."""
+        ...
+
+    def compare_and_swap(self, *, expected_revision: UUID, expected_attempt: UUID | None, replacement: PATStoreRecord) -> bool:
+        """Conditionally and durably replace the complete record.
+
+        :param expected_revision: Credential version that must still be current.
+        :param expected_attempt: Pending marker that must still match, including None.
+        :param replacement: Full next record, with the credential and marker written atomically.
+        :returns: True only after durable commit. False if the comparison failed
+                  and no write occurred. Raise if the outcome cannot be confirmed.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncPATStore(Protocol):
+    """Asynchronous durable, atomic store for one PAT lineage.
+
+    Provide the same strongly consistent reads and durable cross-process
+    compare-and-swap as ``PATStore``. Propagate cancellation. A cancelled
+    write can have committed, and pending state must survive process loss.
+    """
+
+    async def load(self) -> PATStoreRecord | None:
+        """Return the latest committed record, or None for an unseeded lineage."""
+        ...
+
+    async def compare_and_swap(
+        self, *, expected_revision: UUID, expected_attempt: UUID | None, replacement: PATStoreRecord
+    ) -> bool:
+        """Conditionally and durably replace the complete record.
+
+        :param expected_revision: Credential version that must still be current.
+        :param expected_attempt: Pending marker that must still match, including None.
+        :param replacement: Full next record, with the credential and marker written atomically.
+        :returns: True only after durable commit. False if the comparison failed
+                  and no write occurred. Raise if the outcome cannot be confirmed.
+        """
+        ...