mail-intake/mcp_docs/modules/mail_intake.auth.json

{
  "module": "mail_intake.auth",
  "content": {
    "path": "mail_intake.auth",
    "docstring": "Authentication provider implementations for Mail Intake.\n\nThis package defines the **authentication layer** used by mail adapters\nto obtain provider-specific credentials.\n\nIt exposes:\n- A stable, provider-agnostic authentication contract\n- Concrete authentication providers for supported platforms\n\nAuthentication providers:\n- Are responsible for credential acquisition and lifecycle management\n- Are intentionally decoupled from adapter logic\n- May be extended by users to support additional providers\n\nConsumers should depend on the abstract interface and use concrete\nimplementations only where explicitly required.",
    "objects": {
      "MailIntakeAuthProvider": {
        "name": "MailIntakeAuthProvider",
        "kind": "class",
        "path": "mail_intake.auth.MailIntakeAuthProvider",
        "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
        "members": {
          "get_credentials": {
            "name": "get_credentials",
            "kind": "function",
            "path": "mail_intake.auth.MailIntakeAuthProvider.get_credentials",
            "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
            "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
          }
        }
      },
      "MailIntakeGoogleAuth": {
        "name": "MailIntakeGoogleAuth",
        "kind": "class",
        "path": "mail_intake.auth.MailIntakeGoogleAuth",
        "signature": "<bound method Alias.signature of Alias('MailIntakeGoogleAuth', 'mail_intake.auth.google.MailIntakeGoogleAuth')>",
        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nResponsibilities:\n- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n\nThis class is synchronous by design and maintains a minimal internal state.",
        "members": {
          "credentials_path": {
            "name": "credentials_path",
            "kind": "attribute",
            "path": "mail_intake.auth.MailIntakeGoogleAuth.credentials_path",
            "signature": "<bound method Alias.signature of Alias('credentials_path', 'mail_intake.auth.google.MailIntakeGoogleAuth.credentials_path')>",
            "docstring": null
          },
          "store": {
            "name": "store",
            "kind": "attribute",
            "path": "mail_intake.auth.MailIntakeGoogleAuth.store",
            "signature": "<bound method Alias.signature of Alias('store', 'mail_intake.auth.google.MailIntakeGoogleAuth.store')>",
            "docstring": null
          },
          "scopes": {
            "name": "scopes",
            "kind": "attribute",
            "path": "mail_intake.auth.MailIntakeGoogleAuth.scopes",
            "signature": "<bound method Alias.signature of Alias('scopes', 'mail_intake.auth.google.MailIntakeGoogleAuth.scopes')>",
            "docstring": null
          },
          "get_credentials": {
            "name": "get_credentials",
            "kind": "function",
            "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials",
            "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials')>",
            "docstring": "Retrieve valid Google OAuth credentials.\n\nThis method attempts to:\n1. Load cached credentials from the configured credential store\n2. Refresh expired credentials when possible\n3. Perform an interactive OAuth login as a fallback\n4. Persist valid credentials for future use\n\nReturns:\n    A ``google.oauth2.credentials.Credentials`` instance suitable\n    for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError: If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication."
          }
        }
      },
      "base": {
        "name": "base",
        "kind": "module",
        "path": "mail_intake.auth.base",
        "signature": null,
        "docstring": "Authentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
        "members": {
          "ABC": {
            "name": "ABC",
            "kind": "alias",
            "path": "mail_intake.auth.base.ABC",
            "signature": "<bound method Alias.signature of Alias('ABC', 'abc.ABC')>",
            "docstring": null
          },
          "abstractmethod": {
            "name": "abstractmethod",
            "kind": "alias",
            "path": "mail_intake.auth.base.abstractmethod",
            "signature": "<bound method Alias.signature of Alias('abstractmethod', 'abc.abstractmethod')>",
            "docstring": null
          },
          "Generic": {
            "name": "Generic",
            "kind": "alias",
            "path": "mail_intake.auth.base.Generic",
            "signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
            "docstring": null
          },
          "TypeVar": {
            "name": "TypeVar",
            "kind": "alias",
            "path": "mail_intake.auth.base.TypeVar",
            "signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
            "docstring": null
          },
          "T": {
            "name": "T",
            "kind": "attribute",
            "path": "mail_intake.auth.base.T",
            "signature": null,
            "docstring": null
          },
          "MailIntakeAuthProvider": {
            "name": "MailIntakeAuthProvider",
            "kind": "class",
            "path": "mail_intake.auth.base.MailIntakeAuthProvider",
            "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 18, 59)>",
            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
            "members": {
              "get_credentials": {
                "name": "get_credentials",
                "kind": "function",
                "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials",
                "signature": "<bound method Function.signature of Function('get_credentials', 37, 59)>",
                "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
              }
            }
          }
        }
      },
      "google": {
        "name": "google",
        "kind": "module",
        "path": "mail_intake.auth.google",
        "signature": null,
        "docstring": "Google authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n- Credential loading and persistence\n- Token refresh handling\n- Interactive OAuth flow initiation\n- Coordination with a credential persistence layer\n\nNo Google authentication details should leak outside this module.",
        "members": {
          "os": {
            "name": "os",
            "kind": "alias",
            "path": "mail_intake.auth.google.os",
            "signature": "<bound method Alias.signature of Alias('os', 'os')>",
            "docstring": null
          },
          "Sequence": {
            "name": "Sequence",
            "kind": "alias",
            "path": "mail_intake.auth.google.Sequence",
            "signature": "<bound method Alias.signature of Alias('Sequence', 'typing.Sequence')>",
            "docstring": null
          },
          "google": {
            "name": "google",
            "kind": "alias",
            "path": "mail_intake.auth.google.google",
            "signature": "<bound method Alias.signature of Alias('google', 'google')>",
            "docstring": null
          },
          "Request": {
            "name": "Request",
            "kind": "alias",
            "path": "mail_intake.auth.google.Request",
            "signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
            "docstring": null
          },
          "InstalledAppFlow": {
            "name": "InstalledAppFlow",
            "kind": "alias",
            "path": "mail_intake.auth.google.InstalledAppFlow",
            "signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
            "docstring": null
          },
          "Credentials": {
            "name": "Credentials",
            "kind": "alias",
            "path": "mail_intake.auth.google.Credentials",
            "signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
            "docstring": null
          },
          "MailIntakeAuthProvider": {
            "name": "MailIntakeAuthProvider",
            "kind": "class",
            "path": "mail_intake.auth.google.MailIntakeAuthProvider",
            "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nAuthentication providers encapsulate all logic required to:\n- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n\nMail adapters must treat returned credentials as opaque and\nprovider-specific, relying only on the declared credential type\nexpected by the adapter.",
            "members": {
              "get_credentials": {
                "name": "get_credentials",
                "kind": "function",
                "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials",
                "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
                "docstring": "Retrieve valid, provider-specific credentials.\n\nThis method is synchronous by design and represents the sole\nentry point through which adapters obtain authentication\nmaterial.\n\nImplementations must either return credentials of the declared\ntype ``T`` that are valid at the time of return or raise an\nauthentication-specific exception.\n\nReturns:\n    Credentials of type ``T`` suitable for immediate use by the\n    corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated."
              }
            }
          },
          "CredentialStore": {
            "name": "CredentialStore",
            "kind": "class",
            "path": "mail_intake.auth.google.CredentialStore",
            "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
            "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nThis interface separates *credential lifecycle management* from\n*credential storage mechanics*. Implementations are responsible\nonly for persistence concerns, while authentication providers\nretain full control over credential creation, validation, refresh,\nand revocation logic.\n\nThe store is intentionally agnostic to:\n- The concrete credential type being stored\n- The serialization format used to persist credentials\n- The underlying storage backend or durability guarantees",
            "members": {
              "load": {
                "name": "load",
                "kind": "function",
                "path": "mail_intake.auth.google.CredentialStore.load",
                "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
                "docstring": "Load previously persisted credentials.\n\nImplementations should return ``None`` when no credentials are\npresent or when stored credentials cannot be successfully\ndecoded or deserialized.\n\nThe store must not attempt to validate, refresh, or otherwise\ninterpret the returned credentials.\n\nReturns:\n    An instance of type ``T`` if credentials are available and\n    loadable; otherwise ``None``."
              },
              "save": {
                "name": "save",
                "kind": "function",
                "path": "mail_intake.auth.google.CredentialStore.save",
                "signature": "<bound method Alias.signature of Alias('save', 'mail_intake.credentials.store.CredentialStore.save')>",
                "docstring": "Persist credentials to the underlying storage backend.\n\nThis method is invoked when credentials are newly obtained or\nhave been refreshed and are known to be valid at the time of\npersistence.\n\nImplementations are responsible for:\n- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n\nArgs:\n    credentials:\n        The credential object to persist."
              },
              "clear": {
                "name": "clear",
                "kind": "function",
                "path": "mail_intake.auth.google.CredentialStore.clear",
                "signature": "<bound method Alias.signature of Alias('clear', 'mail_intake.credentials.store.CredentialStore.clear')>",
                "docstring": "Remove any persisted credentials from the store.\n\nThis method is called when credentials are known to be invalid,\nrevoked, corrupted, or otherwise unusable, and must ensure that\nno stale authentication material remains accessible.\n\nImplementations should treat this operation as idempotent."
              }
            }
          },
          "MailIntakeAuthError": {
            "name": "MailIntakeAuthError",
            "kind": "class",
            "path": "mail_intake.auth.google.MailIntakeAuthError",
            "signature": "<bound method Alias.signature of Alias('MailIntakeAuthError', 'mail_intake.exceptions.MailIntakeAuthError')>",
            "docstring": "Authentication and credential-related failures.\n\nRaised when authentication providers are unable to acquire,\nrefresh, or persist valid credentials."
          },
          "MailIntakeGoogleAuth": {
            "name": "MailIntakeGoogleAuth",
            "kind": "class",
            "path": "mail_intake.auth.google.MailIntakeGoogleAuth",
            "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 29, 125)>",
            "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nResponsibilities:\n- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n\nThis class is synchronous by design and maintains a minimal internal state.",
            "members": {
              "credentials_path": {
                "name": "credentials_path",
                "kind": "attribute",
                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.credentials_path",
                "signature": null,
                "docstring": null
              },
              "store": {
                "name": "store",
                "kind": "attribute",
                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.store",
                "signature": null,
                "docstring": null
              },
              "scopes": {
                "name": "scopes",
                "kind": "attribute",
                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.scopes",
                "signature": null,
                "docstring": null
              },
              "get_credentials": {
                "name": "get_credentials",
                "kind": "function",
                "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials",
                "signature": "<bound method Function.signature of Function('get_credentials', 70, 125)>",
                "docstring": "Retrieve valid Google OAuth credentials.\n\nThis method attempts to:\n1. Load cached credentials from the configured credential store\n2. Refresh expired credentials when possible\n3. Perform an interactive OAuth login as a fallback\n4. Persist valid credentials for future use\n\nReturns:\n    A ``google.oauth2.credentials.Credentials`` instance suitable\n    for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError: If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication."
              }
            }
          },
          "Any": {
            "name": "Any",
            "kind": "alias",
            "path": "mail_intake.auth.google.Any",
            "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
            "docstring": null
          }
        }
      }
    }
  }
}