270 lines
21 KiB
JSON
270 lines
21 KiB
JSON
{
|
||
"module": "mail_intake.auth",
|
||
"content": {
|
||
"path": "mail_intake.auth",
|
||
"docstring": "# Summary\n\nAuthentication 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\n- A stable, provider-agnostic authentication contract.\n- Concrete authentication providers for supported platforms.\n\nAuthentication providers:\n\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.\n\n---\n\n# Public API\n\n- `MailIntakeAuthProvider`\n- `MailIntakeGoogleAuth`\n\n---",
|
||
"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\nNotes:\n **Responsibilities:**\n\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\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n 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\nReturns:\n T:\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.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception."
|
||
}
|
||
}
|
||
},
|
||
"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\nNotes:\n **Responsibilities:**\n\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\n **Guarantees:**\n\n - This class is synchronous by design and maintains a minimal\n 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\nReturns:\n Credentials:\n A `google.oauth2.credentials.Credentials` instance suitable\n for use with Google API clients.\n\nRaises:\n MailIntakeAuthError:\n If credentials cannot be loaded, refreshed,\n or obtained via interactive authentication.\n\nNotes:\n **Lifecycle:**\n\n - Load cached credentials from the configured credential store.\n - Refresh expired credentials when possible.\n - Perform an interactive OAuth login as a fallback.\n - Persist valid credentials for future use."
|
||
}
|
||
}
|
||
},
|
||
"base": {
|
||
"name": "base",
|
||
"kind": "module",
|
||
"path": "mail_intake.auth.base",
|
||
"signature": null,
|
||
"docstring": "# Summary\n\nAuthentication 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', 20, 68)>",
|
||
"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\nNotes:\n **Responsibilities:**\n\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\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n 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', 44, 68)>",
|
||
"docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n T:\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.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"google": {
|
||
"name": "google",
|
||
"kind": "module",
|
||
"path": "mail_intake.auth.google",
|
||
"signature": null,
|
||
"docstring": "# Summary\n\nGoogle 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\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\nNotes:\n **Responsibilities:**\n\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\n **Constraints:**\n\n - Mail adapters must treat returned credentials as opaque and\n provider-specific.\n - Mail adapters rely only on the declared credential type expected\n 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\nReturns:\n T:\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.\n\nNotes:\n **Guarantees:**\n\n - This method is synchronous by design.\n - Represents the sole entry point through which adapters obtain\n authentication material.\n - Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception."
|
||
}
|
||
}
|
||
},
|
||
"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.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The 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\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
|
||
},
|
||
"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\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials"
|
||
},
|
||
"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\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations 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\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials."
|
||
},
|
||
"MailIntakeGoogleAuth": {
|
||
"name": "MailIntakeGoogleAuth",
|
||
"kind": "class",
|
||
"path": "mail_intake.auth.google.MailIntakeGoogleAuth",
|
||
"signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 32, 135)>",
|
||
"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\nNotes:\n **Responsibilities:**\n\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\n **Guarantees:**\n\n - This class is synchronous by design and maintains a minimal\n 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', 76, 135)>",
|
||
"docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n Credentials:\n A `google.oauth2.credentials.Credentials` instance suitable\n for use with Google API clients.\n\nRaises:\n MailIntakeAuthError:\n If credentials cannot be loaded, refreshed,\n or obtained via interactive authentication.\n\nNotes:\n **Lifecycle:**\n\n - Load cached credentials from the configured credential store.\n - Refresh expired credentials when possible.\n - Perform an interactive OAuth login as a fallback.\n - Persist valid credentials for future use."
|
||
}
|
||
}
|
||
},
|
||
"Any": {
|
||
"name": "Any",
|
||
"kind": "alias",
|
||
"path": "mail_intake.auth.google.Any",
|
||
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
|
||
"docstring": null
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
} |