updated mcp
All checks were successful
continuous-integration/drone/push Build is passing

This commit is contained in:
2026-03-08 17:57:34 +05:30
parent 9191de9dff
commit 0e49f02c4c
167 changed files with 7632 additions and 98942 deletions

View File

@@ -1566,29 +1566,29 @@
<div class="doc doc-contents first">
<p>Credential persistence interfaces and implementations for Mail Intake.</p>
<hr />
<h4 id="mail_intake.credentials--summary">Summary</h4>
<h3 id="mail_intake.credentials--summary">Summary</h3>
<p>Credential persistence interfaces and implementations for Mail Intake.</p>
<p>This package defines the abstractions and concrete implementations used
to persist authentication credentials across Mail Intake components.</p>
<p>The credential persistence layer is intentionally decoupled from
authentication logic. Authentication providers are responsible for
credential acquisition, validation, and refresh, while implementations
within this package are responsible solely for storage and retrieval.</p>
<p>The package provides:
- A generic <code>CredentialStore</code> abstraction defining the persistence contract
- Local filesystembased storage for development and single-node use
- Distributed, Redis-backed storage for production and scaled deployments</p>
<p>The package provides:</p>
<ul>
<li>A generic <code>CredentialStore</code> abstraction defining the persistence contract.</li>
<li>Local filesystembased storage for development and single-node use.</li>
<li>Distributed, Redis-backed storage for production and scaled deployments.</li>
</ul>
<p>Credential lifecycle management, interpretation, and security policy
decisions remain the responsibility of authentication providers.</p>
<hr />
<h4 id="mail_intake.credentials--public-api">Public API</h4>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>CredentialStore
PickleCredentialStore
RedisCredentialStore
</code></pre></div></td></tr></table></div>
<h3 id="mail_intake.credentials--public-api">Public API</h3>
<ul>
<li><code>CredentialStore</code></li>
<li><code>PickleCredentialStore</code></li>
<li><code>RedisCredentialStore</code></li>
</ul>
<hr />
@@ -1618,25 +1618,27 @@ RedisCredentialStore
Bases: <code><span title="abc.ABC">ABC</span></code>, <code><span title="typing.Generic">Generic</span>[<span title="mail_intake.credentials.store.T">T</span>]</code></p>
<p>Abstract base class defining a generic persistence interface for
authentication credentials.</p>
<p>Abstract base class defining a generic persistence interface.</p>
<p>Used for authentication credentials across different backends.</p>
<details class="notes" open>
<summary>Notes</summary>
<p><strong>Responsibilities:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- Provide persistent storage separating life-cycle management from storage mechanics
- Keep implementation focused only on persistence
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>- Provide persistent storage separating life-cycle management from
storage mechanics.
- Keep implementation focused only on persistence.
</code></pre></div></td></tr></table></div>
<p><strong>Constraints:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div><pre><span></span><code>- The store is intentionally agnostic to:
- The concrete credential type being stored
- The serialization format used to persist credentials
- The underlying storage backend or durability guarantees
- The concrete credential type being stored.
- The serialization format used to persist credentials.
- The underlying storage backend or durability guarantees.
</code></pre></div></td></tr></table></div>
</details>
@@ -1736,8 +1738,14 @@ loadable; otherwise <code>None</code>.</p>
<summary>Notes</summary>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized
- The store must not attempt to validate, refresh, or otherwise interpret the returned credentials
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span></pre></div></td><td class="code"><div><pre><span></span><code>- Implementations should return `None` when no credentials are
present or when stored credentials cannot be successfully
decoded or deserialized.
- The store must not attempt to validate, refresh, or otherwise
interpret the returned credentials.
</code></pre></div></td></tr></table></div>
</details>
</div>
@@ -1832,7 +1840,7 @@ loadable; otherwise <code>None</code>.</p>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><a class="autorefs autorefs-internal" title="mail_intake.credentials.store.CredentialStore" href="../mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore">CredentialStore</a>[<span title="mail_intake.credentials.pickle.T">T</span>]</code></p>
Bases: <code><a class="autorefs autorefs-internal" title="mail_intake.credentials.store.CredentialStore" href="store/#mail_intake.credentials.store.CredentialStore">CredentialStore</a>[<span title="mail_intake.credentials.pickle.T">T</span>]</code></p>
<p>Filesystem-backed credential store using pickle serialization.</p>
@@ -1846,12 +1854,14 @@ development, testing, and single-process execution contexts.</p>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>- Stores credentials on the local filesystem
- Uses pickle for serialization and deserialization
- Does not provide encryption, locking, or concurrency guarantees
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>- Stores credentials on the local filesystem.
- Uses `pickle` for serialization and deserialization.
- Does not provide encryption, locking, or concurrency guarantees.
</code></pre></div></td></tr></table></div>
<p><strong>Constraints:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><code>- Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- Credential lifecycle management, validation, and refresh logic are
explicitly out of scope for this class.
</code></pre></div></td></tr></table></div>
</details>
<p>Initialize a pickle-backed credential store.</p>
@@ -1970,8 +1980,12 @@ successfully deserialized; otherwise <code>None</code>.</p>
<summary>Notes</summary>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``
- The store does not attempt to validate or interpret the returned credentials
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div><pre><span></span><code>- If the credential file does not exist or cannot be successfully
deserialized, this method returns `None`.
- The store does not attempt to validate or interpret the
returned credentials.
</code></pre></div></td></tr></table></div>
</details>
</div>
@@ -2055,7 +2069,7 @@ successfully deserialized; otherwise <code>None</code>.</p>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><a class="autorefs autorefs-internal" title="mail_intake.credentials.store.CredentialStore" href="../mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore">CredentialStore</a>[<span title="mail_intake.credentials.redis.T">T</span>]</code></p>
Bases: <code><a class="autorefs autorefs-internal" title="mail_intake.credentials.store.CredentialStore" href="store/#mail_intake.credentials.store.CredentialStore">CredentialStore</a>[<span title="mail_intake.credentials.redis.T">T</span>]</code></p>
<p>Redis-backed implementation of <code>CredentialStore</code>.</p>
@@ -2068,13 +2082,19 @@ must be shared across multiple processes or nodes.</p>
<summary>Notes</summary>
<p><strong>Responsibilities:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- This class is responsible only for persistence and retrieval
- It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>- This class is responsible only for persistence and retrieval.
- It does not interpret, validate, refresh, or otherwise manage the
lifecycle of the credentials being stored.
</code></pre></div></td></tr></table></div>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- The store is intentionally generic and delegates all serialization concerns to caller-provided functions
- This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div><pre><span></span><code>- The store is intentionally generic and delegates all serialization
concerns to caller-provided functions.
- This avoids unsafe mechanisms such as `pickle` and allows
credential formats to be explicitly controlled and audited.
</code></pre></div></td></tr></table></div>
</details>
<p>Initialize a Redis-backed credential store.</p>
@@ -2250,8 +2270,16 @@ successfully deserialized; otherwise <code>None</code>.</p>
<summary>Notes</summary>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``
- The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span></pre></div></td><td class="code"><div><pre><span></span><code>- If no value exists for the configured key, or if the stored
payload cannot be successfully deserialized, this method
returns `None`.
- The store does not attempt to validate the returned
credentials or determine whether they are expired or
otherwise usable.
</code></pre></div></td></tr></table></div>
</details>
</div>

View File

@@ -1320,15 +1320,14 @@
<div class="doc doc-contents first">
<p>Local filesystembased credential persistence for Mail Intake.</p>
<hr />
<h4 id="mail_intake.credentials.pickle--summary">Summary</h4>
<h3 id="mail_intake.credentials.pickle--summary">Summary</h3>
<p>Local filesystembased credential persistence for Mail Intake.</p>
<p>This module provides a file-backed implementation of the
<code>CredentialStore</code> abstraction using Python's <code>pickle</code> module.</p>
<p>The pickle-based credential store is intended for local development,
<p>The <code>pickle</code>-based credential store is intended for local development,
single-node deployments, and controlled environments where credentials
do not need to be shared across processes or machines.</p>
<p>Due to the security and portability risks associated with pickle-based
<p>Due to the security and portability risks associated with <code>pickle</code>-based
serialization, this implementation is not suitable for distributed or
untrusted environments.</p>
@@ -1357,7 +1356,7 @@ untrusted environments.</p>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><a class="autorefs autorefs-internal" title="mail_intake.credentials.store.CredentialStore" href="../../mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore">CredentialStore</a>[<span title="mail_intake.credentials.pickle.T">T</span>]</code></p>
Bases: <code><a class="autorefs autorefs-internal" title="mail_intake.credentials.store.CredentialStore" href="../store/#mail_intake.credentials.store.CredentialStore">CredentialStore</a>[<span title="mail_intake.credentials.pickle.T">T</span>]</code></p>
<p>Filesystem-backed credential store using pickle serialization.</p>
@@ -1371,12 +1370,14 @@ development, testing, and single-process execution contexts.</p>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>- Stores credentials on the local filesystem
- Uses pickle for serialization and deserialization
- Does not provide encryption, locking, or concurrency guarantees
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>- Stores credentials on the local filesystem.
- Uses `pickle` for serialization and deserialization.
- Does not provide encryption, locking, or concurrency guarantees.
</code></pre></div></td></tr></table></div>
<p><strong>Constraints:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><code>- Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- Credential lifecycle management, validation, and refresh logic are
explicitly out of scope for this class.
</code></pre></div></td></tr></table></div>
</details>
<p>Initialize a pickle-backed credential store.</p>
@@ -1495,8 +1496,12 @@ successfully deserialized; otherwise <code>None</code>.</p>
<summary>Notes</summary>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``
- The store does not attempt to validate or interpret the returned credentials
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div><pre><span></span><code>- If the credential file does not exist or cannot be successfully
deserialized, this method returns `None`.
- The store does not attempt to validate or interpret the
returned credentials.
</code></pre></div></td></tr></table></div>
</details>
</div>

View File

@@ -1320,9 +1320,8 @@
<div class="doc doc-contents first">
<p>Redis-backed credential persistence for Mail Intake.</p>
<hr />
<h4 id="mail_intake.credentials.redis--summary">Summary</h4>
<h3 id="mail_intake.credentials.redis--summary">Summary</h3>
<p>Redis-backed credential persistence for Mail Intake.</p>
<p>This module provides a Redis-based implementation of the
<code>CredentialStore</code> abstraction, enabling credential persistence
across distributed and horizontally scaled deployments.</p>
@@ -1330,11 +1329,13 @@ across distributed and horizontally scaled deployments.</p>
authentication credentials must be shared safely across multiple
processes, containers, or nodes, such as container orchestration
platforms and microservice architectures.</p>
<p>Key characteristics:
- Distributed-safe, shared storage using Redis
- Explicit, caller-defined serialization and deserialization
- No reliance on unsafe mechanisms such as pickle
- Optional time-to-live (TTL) support for automatic credential expiry</p>
<p>Key characteristics:</p>
<ul>
<li>Distributed-safe, shared storage using Redis.</li>
<li>Explicit, caller-defined serialization and deserialization.</li>
<li>No reliance on unsafe mechanisms such as <code>pickle</code>.</li>
<li>Optional time-to-live (TTL) support for automatic credential expiry.</li>
</ul>
<p>This module is responsible solely for persistence concerns.
Credential validation, refresh, rotation, and acquisition remain the
responsibility of authentication provider implementations.</p>
@@ -1364,7 +1365,7 @@ responsibility of authentication provider implementations.</p>
<div class="doc doc-contents ">
<p class="doc doc-class-bases">
Bases: <code><a class="autorefs autorefs-internal" title="mail_intake.credentials.store.CredentialStore" href="../../mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore">CredentialStore</a>[<span title="mail_intake.credentials.redis.T">T</span>]</code></p>
Bases: <code><a class="autorefs autorefs-internal" title="mail_intake.credentials.store.CredentialStore" href="../store/#mail_intake.credentials.store.CredentialStore">CredentialStore</a>[<span title="mail_intake.credentials.redis.T">T</span>]</code></p>
<p>Redis-backed implementation of <code>CredentialStore</code>.</p>
@@ -1377,13 +1378,19 @@ must be shared across multiple processes or nodes.</p>
<summary>Notes</summary>
<p><strong>Responsibilities:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- This class is responsible only for persistence and retrieval
- It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>- This class is responsible only for persistence and retrieval.
- It does not interpret, validate, refresh, or otherwise manage the
lifecycle of the credentials being stored.
</code></pre></div></td></tr></table></div>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- The store is intentionally generic and delegates all serialization concerns to caller-provided functions
- This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div><pre><span></span><code>- The store is intentionally generic and delegates all serialization
concerns to caller-provided functions.
- This avoids unsafe mechanisms such as `pickle` and allows
credential formats to be explicitly controlled and audited.
</code></pre></div></td></tr></table></div>
</details>
<p>Initialize a Redis-backed credential store.</p>
@@ -1559,8 +1566,16 @@ successfully deserialized; otherwise <code>None</code>.</p>
<summary>Notes</summary>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``
- The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span></pre></div></td><td class="code"><div><pre><span></span><code>- If no value exists for the configured key, or if the stored
payload cannot be successfully deserialized, this method
returns `None`.
- The store does not attempt to validate the returned
credentials or determine whether they are expired or
otherwise usable.
</code></pre></div></td></tr></table></div>
</details>
</div>

View File

@@ -1320,9 +1320,8 @@
<div class="doc doc-contents first">
<p>Credential persistence abstractions for Mail Intake.</p>
<hr />
<h4 id="mail_intake.credentials.store--summary">Summary</h4>
<h3 id="mail_intake.credentials.store--summary">Summary</h3>
<p>Credential persistence abstractions for Mail Intake.</p>
<p>This module defines the generic persistence contract used to store and
retrieve authentication credentials across Mail Intake components.</p>
<p>The <code>CredentialStore</code> abstraction establishes a strict separation
@@ -1363,25 +1362,27 @@ specific storage mechanism.</p>
Bases: <code><span title="abc.ABC">ABC</span></code>, <code><span title="typing.Generic">Generic</span>[<span title="mail_intake.credentials.store.T">T</span>]</code></p>
<p>Abstract base class defining a generic persistence interface for
authentication credentials.</p>
<p>Abstract base class defining a generic persistence interface.</p>
<p>Used for authentication credentials across different backends.</p>
<details class="notes" open>
<summary>Notes</summary>
<p><strong>Responsibilities:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- Provide persistent storage separating life-cycle management from storage mechanics
- Keep implementation focused only on persistence
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><code>- Provide persistent storage separating life-cycle management from
storage mechanics.
- Keep implementation focused only on persistence.
</code></pre></div></td></tr></table></div>
<p><strong>Constraints:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div><pre><span></span><code>- The store is intentionally agnostic to:
- The concrete credential type being stored
- The serialization format used to persist credentials
- The underlying storage backend or durability guarantees
- The concrete credential type being stored.
- The serialization format used to persist credentials.
- The underlying storage backend or durability guarantees.
</code></pre></div></td></tr></table></div>
</details>
@@ -1481,8 +1482,14 @@ loadable; otherwise <code>None</code>.</p>
<summary>Notes</summary>
<p><strong>Guarantees:</strong></p>
<div class="language-text highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div><pre><span></span><code>- Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized
- The store must not attempt to validate, refresh, or otherwise interpret the returned credentials
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span></pre></div></td><td class="code"><div><pre><span></span><code>- Implementations should return `None` when no credentials are
present or when stored credentials cannot be successfully
decoded or deserialized.
- The store must not attempt to validate, refresh, or otherwise
interpret the returned credentials.
</code></pre></div></td></tr></table></div>
</details>
</div>