Metadata-Version: 2.4
Name: lexigram-secrets
Version: 0.1.3005
Summary: Secret vaults with rotation, tenant scoping, and audit for Lexigram Framework
Project-URL: Homepage, https://lexigram.dev
Project-URL: Repository, https://github.com/dbtinoy-/lexigram
Project-URL: Documentation, https://docs.lexigram.dev
Project-URL: Issues, https://github.com/dbtinoy-/lexigram/issues
Project-URL: Changelog, https://github.com/dbtinoy-/lexigram/blob/main/CHANGELOG.md
Author-email: Lexigram Framework Team <team@lexigram.dev>
Maintainer-email: Lexigram Framework Team <team@lexigram.dev>
License: MIT
License-File: LICENSE
Keywords: credentials,rotation,secrets,security,vault
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: botocore>=1.40.61
Requires-Dist: lexigram-contracts>=0.1.0
Requires-Dist: lexigram>=0.1.1
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: all
Requires-Dist: aioboto3>=10.0.0; extra == 'all'
Requires-Dist: azure-identity>=1.0.0; extra == 'all'
Requires-Dist: azure-keyvault-secrets>=4.0.0; extra == 'all'
Requires-Dist: google-cloud-secret-manager>=2.0.0; extra == 'all'
Requires-Dist: hvac>=2.0.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: aioboto3>=10.0.0; extra == 'aws'
Provides-Extra: azure
Requires-Dist: azure-identity>=1.0.0; extra == 'azure'
Requires-Dist: azure-keyvault-secrets>=4.0.0; extra == 'azure'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: gcp
Requires-Dist: google-cloud-secret-manager>=2.0.0; extra == 'gcp'
Provides-Extra: test
Requires-Dist: lexigram-testing>=0.1.1; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Provides-Extra: vault
Requires-Dist: hvac>=2.0.0; extra == 'vault'
Description-Content-Type: text/markdown

# lexigram-secrets

Secret vaults with rotation, tenant isolation, and audit logging for the Lexigram Framework.
Supports HashiCorp Vault and in-memory backends with automatic key rotation, version tracking,
and tenant-scoped secret stores.

---

## Overview

lexigram-secrets provides a `RotatableSecretStoreProtocol`-based secret management system
with versioned rotation, tenant isolation, audit logging, and pluggable backends. All services
are wired via `SecretsProvider`, which registers the secret store and rotation decorator
with the DI container.

---

> Full documentation: [docs.lexigram.dev](https://docs.lexigram.dev)
## Install

```bash
uv add lexigram-secrets
# Optional extras
uv add "lexigram-secrets[vault]"    # HashiCorp Vault backend
uv add "lexigram-secrets[aws]"      # AWS Secrets Manager backend
uv add "lexigram-secrets[gcp]"      # GCP Secret Manager backend
```

## Quick Start

```python
from lexigram import Application
from lexigram.di.module import Module, module
from lexigram.secrets import SecretsModule

@module(imports=[SecretsModule.configure()])
class AppModule(Module):
    pass

app = Application(modules=[AppModule])
if __name__ == "__main__":
    app.run()
```

## Module Factory Methods

| Method | Description |
|--------|-------------|
| `SecretsModule.configure(config)` | Configure with explicit SecretsConfig |
| `SecretsModule.stub()` | Minimal config for testing (memory backend) |

## Key Features

- **Versioned secrets** — Every `set` and `rotate` creates a new version; full history retained
- **Automatic rotation** — `RotationDecorator` wraps any service method with age-checked rotation
- **Tenant isolation** — `TenantScopedSecretStore` prefixes keys per tenant for multi-tenant apps
- **Audit logging** — `SecretAuditDecorator` logs all store operations through `AuditLoggerProtocol`
- **Pluggable backends** — `HashicorpVaultStore` (KV v2) and in-memory (`FakeRotatableSecretStore`)
- **Bulk operations** — `get_bulk` for fetching multiple secrets at once
- **Version introspection** — `list_versions` and `get_version` for audit and rollback workflows

## Testing

```python
from lexigram.testing.fakes import FakeRotatableSecretStore
from lexigram.testing.compliance import StoreConformanceSuite

class TestMyStore(StoreConformanceSuite):
    @pytest.fixture
    def make_store(self):
        return FakeRotatableSecretStore
```

## Key Source Files

| File | What it contains |
|------|----------------|
| `src/lexigram/secrets/module.py` | `SecretsModule` class with factory methods |
| `src/lexigram/secrets/di/provider.py` | `SecretsProvider` — wires secret store into DI container |
| `src/lexigram/secrets/config.py` | `SecretsConfig` and backend selection |
| `src/lexigram/secrets/types.py` | `RotatableSecretStoreProtocol`, `VersionedSecret`, `SecretVersion` |
| `src/lexigram/secrets/rotation/` | `RotationDecorator` and `RotationSchedule` for automatic key rotation |
| `src/lexigram/secrets/tenancy/` | `TenantScopedSecretStore` for multi-tenant key isolation |
| `src/lexigram/secrets/audit/` | `SecretAuditDecorator` for operation audit logging |
| `src/lexigram/secrets/backends/` | Backend implementations (Vault, etc.) |

## Config Reference

| Field | Default | Env var | Description |
|-------|---------|---------|-------------|
| `secrets.enabled` | `true` | `LEX_SECRETS__ENABLED` | Enable the secrets subsystem |
| `secrets.backend_type` | `memory` | `LEX_SECRETS__BACKEND_TYPE` | Backend store type (`memory`, `vault`) |
| `secrets.max_age_seconds` | `86400` | `LEX_SECRETS__MAX_AGE_SECONDS` | Max age before automatic rotation |
| `secrets.warning_before_seconds` | `3600` | `LEX_SECRETS__WARNING_BEFORE_SECONDS` | Seconds before expiry to emit warnings |
| `secrets.tenant_id` | `null` | `LEX_SECRETS__TENANT_ID` | Optional tenant namespace |
| `secrets.audit_actor_id` | `secrets` | `LEX_SECRETS__AUDIT_ACTOR_ID` | Actor identifier for audit logs |
