Vishesh 'ironeagle' Bangotra
b1447fb72b
Adds the mail-intake wiki to the hub alongside lib and mcp and picks up the regenerated flat lib reference and standardized MCP modules.
193 lines
17 KiB
JSON
193 lines
17 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": null,
|
||
"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": "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": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])",
|
||
"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": null,
|
||
"docstring": null
|
||
},
|
||
"store": {
|
||
"name": "store",
|
||
"kind": "attribute",
|
||
"path": "mail_intake.auth.MailIntakeGoogleAuth.store",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"scopes": {
|
||
"name": "scopes",
|
||
"kind": "attribute",
|
||
"path": "mail_intake.auth.MailIntakeGoogleAuth.scopes",
|
||
"signature": null,
|
||
"docstring": null
|
||
},
|
||
"get_credentials": {
|
||
"name": "get_credentials",
|
||
"kind": "function",
|
||
"path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials",
|
||
"signature": "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": {
|
||
"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": null,
|
||
"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": "get_credentials() -> T",
|
||
"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": {
|
||
"MailIntakeAuthProvider": {
|
||
"name": "MailIntakeAuthProvider",
|
||
"kind": "class",
|
||
"path": "mail_intake.auth.google.MailIntakeAuthProvider",
|
||
"signature": null,
|
||
"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": "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": null,
|
||
"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": "load()",
|
||
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\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": "save(credentials: T)",
|
||
"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": "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": null,
|
||
"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": "MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])",
|
||
"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": "get_credentials() -> Any",
|
||
"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."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
} |