credential-bridge 0.1.0__tar.gz

credential_bridge-0.1.0/.github/workflows/publish-zensical.yml

@@ -0,0 +1,123 @@
+# ==============================================================================
+# 📚 Reusable Workflow: Deploy Zensical Docs to GitHub Pages
+# ==============================================================================
+# USAGE — call this from your project repo:
+#
+#   jobs:
+#     docs:
+#       uses: your-org/.github/.github/workflows/publish-zensical.yml@main
+#       with:
+#         python-version: '3.11'           # must be 3.10+ (Zensical requirement)
+#         docs-requirements: 'requirements-docs.txt'
+#         src-layout: true
+#       secrets: inherit
+#
+# SETUP:
+#   1. Store this file in your shared `.github` repo under .github/workflows/
+#   2. Create requirements-docs.txt with pinned docs dependencies:
+#        zensical>=0.0.39
+#        mkdocstrings[python]>=0.24
+#        mkdocs-autorefs>=1.0
+#   3. Add zensical.toml to your project root (config file for Zensical)
+#   4. Enable GitHub Pages: Settings → Pages → Source: GitHub Actions
+# ==============================================================================
+
+name: 📚 Deploy Zensical Docs to GitHub Pages
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        description: "Python version (must be 3.10+ — Zensical requirement)"
+        type: string
+        default: "3.11"
+      docs-requirements:
+        description: "Path to pip requirements file for docs dependencies"
+        type: string
+        default: "requirements-docs.txt"
+      src-layout:
+        description: "Set true if project uses src/ layout (adds src/ to PYTHONPATH)"
+        type: boolean
+        default: false
+      working-directory:
+        description: "Working directory (monorepo support)"
+        type: string
+        default: "."
+
+  # Allow direct triggering for testing
+  workflow_dispatch:
+    inputs:
+      python-version:
+        description: "Python version (must be 3.10+)"
+        type: string
+        default: "3.11"
+
+# Minimal, scoped permissions (principle of least privilege)
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Prevent concurrent deployments — queue them instead of cancelling
+concurrency:
+  group: "pages-deploy"
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    name: 🔨 Build Docs
+    if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory || '.' }}
+
+    steps:
+      - name: 🔄 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history — useful for version tags and future git plugins
+
+      - name: 🐍 Set up Python ${{ inputs.python-version || '3.11' }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs.python-version || '3.11' }}
+
+      # Cache pip downloads to speed up repeat builds
+      - name: 💾 Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: docs-pip-${{ runner.os }}-${{ inputs.python-version || '3.11' }}-${{ hashFiles(inputs.docs-requirements || 'requirements-docs.txt') }}
+          restore-keys: |
+            docs-pip-${{ runner.os }}-${{ inputs.python-version || '3.11' }}-
+
+      - name: 📦 Install doc dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r ${{ inputs.docs-requirements || 'requirements-docs.txt' }}
+
+      - name: 🔧 Configure PYTHONPATH for src layout
+        if: ${{ inputs.src-layout == true }}
+        run: echo "PYTHONPATH=$PYTHONPATH:$(pwd)/src" >> $GITHUB_ENV
+
+      - name: 🔨 Build Zensical site
+        run: zensical build
+
+      # Upload using the official GitHub Pages artifact action
+      - name: 📤 Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{ inputs.working-directory || '.' }}/public
+
+  deploy-docs:
+    name: 🚀 Deploy to GitHub Pages
+    needs: build-docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - name: 🚀 Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

credential_bridge-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,116 @@
+# ==============================================================================
+# 🚢 Release Workflow — Project Caller
+# ==============================================================================
+# Save this file in YOUR PROJECT repo at:
+#   .github/workflows/release.yml
+#
+# TRIGGERS & JOB MATRIX:
+#
+#   Event            │ docs │ publish
+#   ─────────────────┼──────┼────────
+#   Push to main     │  ✅  │   ⛔
+#   Push tag X.X.X   │  ⛔  │   ✅
+#   Manual dispatch  │  ✅  │   ⛔
+#
+# PUBLISH TARGET FLAG (controls where the package is published):
+#
+#   publish-target: 'both'     → TestPyPI first, then PyPI  ← default
+#   publish-target: 'pypi'     → PyPI only
+#   publish-target: 'testpypi' → TestPyPI only
+#
+# RELEASE FLOW:
+#   1. Merge PRs to main as normal — docs deploy automatically
+#   2. When ready to release, push a bare SemVer tag:
+#        git tag 1.2.1
+#        git push origin 1.2.1
+#   3. The publish job runs: validate → test → build → testpypi → pypi
+#
+# SECRETS REQUIRED (Settings → Secrets and variables → Actions):
+#   TEST_PYPI_API_TOKEN  — from test.pypi.org/manage/account/token/
+#   PYPI_API_TOKEN       — from pypi.org (only if not using Trusted Publishing)
+#
+# PRE-REQUISITES (once per project):
+#
+#   1. Enable GitHub Pages:
+#      Settings → Pages → Source → GitHub Actions
+#
+#   2. Create GitHub Environments:
+#      Settings → Environments → New environment
+#        - "pypi"      (real PyPI — add Required reviewers for safety)
+#        - "test-pypi" (TestPyPI sandbox — no reviewers needed)
+#
+#   3. Register Trusted Publisher on pypi.org:
+#      pypi.org → your project → Publishing → Add publisher
+#        owner    = vertex-ai-automations
+#        repo     = THIS-REPO-NAME
+#        workflow = release.yml
+#        env      = pypi
+#
+#   4. Create requirements-docs.txt:
+#        zensical>=0.0.39
+#        mkdocstrings[python]>=0.24
+#        mkdocs-autorefs>=1.0
+#
+# CUSTOMISE PER PROJECT:
+#   python-version   — match your project's Python version
+#   test-command     — your test runner command
+#   publish-target   — 'both' | 'pypi' | 'testpypi'
+#   src-layout       — true if you use a src/ directory layout
+#   mkdocs-strict    — false to allow doc build warnings
+# ==============================================================================
+
+name: 🚢 Release
+
+on:
+  push:
+    branches:
+      - main          # Docs deploy only
+    tags:
+      - "*.*.*"       # Publish only — bare SemVer e.g. 1.2.1
+  workflow_dispatch:  # Manual trigger — docs only
+
+jobs:
+
+  # ============================================================
+  # 📚 Deploy Zensical Docs to GitHub Pages
+  # Runs on: push to main, manual dispatch
+  # ============================================================
+  docs:
+    name: 📚 Deploy Docs
+    uses: vertex-ai-automations/shared-workflows/.github/workflows/publish-zensical.yml@main
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      python-version: "3.11"            # must be 3.10+ (Zensical requirement)
+      docs-requirements: "requirements-docs.txt"
+      src-layout: true                   # ← set false if not using src/ layout
+    secrets: inherit
+
+  # ============================================================
+  # 📦 Build and Publish Package
+  # Runs on: tag push only (tag guard is enforced inside the
+  # reusable workflow — non-tag pushes skip cleanly)
+  #
+  # publish-target controls which registries receive the package:
+  #   'both'     → TestPyPI first, then PyPI (recommended)
+  #   'pypi'     → PyPI only
+  #   'testpypi' → TestPyPI only
+  #
+  # No permissions block needed — declared inside python-publish.yml
+  # ============================================================
+  publish:
+    name: 📦 Publish Package
+    uses: vertex-ai-automations/shared-workflows/.github/workflows/python-publish.yml@main
+    permissions:
+      contents: read
+      id-token: write
+    with:
+      python-version: "3.11"
+      run-tests: true
+      test-command: "pytest tests/ -v --tb=short"
+      publish-target: "both"          # 'both' | 'pypi' | 'testpypi' — publishes to TestPyPI first, then PyPI
+      use-trusted-publishing: false    # set false to use PYPI_API_TOKEN instead (must be set in Settings → Secrets → Actions)
+    secrets: inherit
+

credential_bridge-0.1.0/.gitignore

@@ -0,0 +1,97 @@
+# ── Generated files ────────────────────────────────────────────────────────────
+# setuptools_scm writes this at build/install time — never commit it
+src/credential_bridge/_version.py
+
+# ── Python ─────────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+MANIFEST
+.installed.cfg
+
+# Build / dist
+build/
+dist/
+wheels/
+share/python-wheels/
+develop-eggs/
+eggs/
+.eggs/
+sdist/
+parts/
+var/
+lib/
+lib64/
+downloads/
+.Python
+
+# ── Virtual environments ────────────────────────────────────────────────────────
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# ── Testing ─────────────────────────────────────────────────────────────────────
+.pytest_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+htmlcov/
+coverage.xml
+*.cover
+*.py,cover
+nosetests.xml
+.hypothesis/
+cover/
+
+# ── Type checkers ──────────────────────────────────────────────────────────────
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# ── Docs build output ──────────────────────────────────────────────────────────
+/public
+/site
+
+# ── Internal planning (spec/plan files) ────────────────────────────────────────
+docs/superpowers/
+
+# ── Playwright MCP test artifacts ──────────────────────────────────────────────
+.playwright-mcp/
+
+# ── EnvFileBackend atomic write temp files ─────────────────────────────────────
+*.env.tmp
+
+# ── Editors / IDEs ─────────────────────────────────────────────────────────────
+.vscode/
+.idea/
+.ropeproject
+.spyderproject
+.spyproject
+
+# ── System ─────────────────────────────────────────────────────────────────────
+.DS_Store
+*.swp
+*.log
+*.err
+
+# ── Jupyter ────────────────────────────────────────────────────────────────────
+*.ipynb_checkpoints
+profile_default/
+ipython_config.py
+
+# ── PyInstaller ────────────────────────────────────────────────────────────────
+*.manifest
+
+# ── PEP 582 ────────────────────────────────────────────────────────────────────
+__pypackages__/

credential_bridge-0.1.0/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**credential-bridge** is a Python 3.8+ secrets management library with a plugin backend architecture. It supports HashiCorp Vault (KV-v2), OS system keyring, and .env files through a unified interface. Ships five CLI entry points: `cb`, `vault-cli`, `keyring-cli`, `env-cli`, and `run-wizard`.
+
+## Development Setup
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/unit/
+
+# Run integration tests (requires external services)
+pytest tests/integration/ -m integration
+
+# Serve docs locally (Zensical — uses zensical.toml)
+zensical serve
+
+# Build docs
+zensical build
+
+# Lint
+ruff check src/
+
+# Type check
+mypy src/
+```
+
+Version is auto-generated from git tags via `setuptools_scm` — never commit `_version.py` (it is in `.gitignore`). Run `pip install -e .` to regenerate it after tagging.
+
+## Architecture
+
+```
+src/credential_bridge/
+├── backends/
+│   ├── base.py          # BaseSecretBackend ABC — 5 abstract methods + backend_name
+│   ├── vault.py         # VaultBackend: HashiCorp Vault KV-v2
+│   ├── keyring.py       # KeyringBackend: OS keyring (JSON-serialised dict per entry)
+│   └── env_file.py      # EnvFileBackend: .env file CRUD with atomic writes
+├── cli/
+│   ├── main.py          # Unified `cb` entry point (Typer, composes sub-apps)
+│   ├── vault_cli.py     # vault-cli (Typer + Rich)
+│   ├── keyring_cli.py   # keyring-cli (Typer + Rich)
+│   └── env_cli.py       # env-cli (Typer + Rich)
+├── exceptions.py        # Typed hierarchy: CredentialBridgeError → BackendError → ...
+├── manager.py           # SecretsManager facade + class-level backend registry
+├── prompt_wizard.py     # Interactive wizard (prompt_toolkit)
+└── utils.py             # Config I/O (~/.vault_config.json), get_session()
+```
+
+**Key design decisions:**
+- `BaseSecretBackend` enforces `backend_name` via `__init_subclass__` — forgetting to set it raises `TypeError` at class definition time.
+- `SecretsManager._registry` is a class-level dict. `register_backend("name", MyBackend)` is how third-party backends plug in. Tests must use a `clean_registry` autouse fixture to isolate state.
+- `VaultBackend` URL resolution: `vault_url` arg → `VAULT_ADDR` env var → `~/.vault_config.json` → `ConfigurationError`.
+- `VaultBackend(persist=False)` is the default — credentials are NOT written to `~/.vault_config.json` unless `persist=True` is explicitly passed.
+- `KeyringBackend` serialises the secret dict to JSON before storing (keyring stores one string per key). `get_secret` deserialises on retrieval.
+- `EnvFileBackend` uses `os.replace()` for atomic writes (write to `.env.tmp`, rename). Values with spaces or special chars are double-quoted.
+- All logging goes through `PyLogShield` for sensitive data masking. Both `VaultBackend` and `KeyringBackend` accept an optional `logger: PyLogShield` parameter.
+- TLS verification is enabled by default (`verify=True`). Pass `cert="/path/to/ca.pem"` for custom CA bundles.
+
+## Exception Hierarchy
+
+```
+CredentialBridgeError
+├── BackendError
+│   ├── VaultError
+│   │   ├── VaultAuthError          — bad token / AppRole
+│   │   ├── VaultConnectionError    — unreachable server
+│   │   └── VaultSecretNotFoundError — secret path does not exist
+│   ├── KeyringError
+│   └── EnvFileError
+│       ├── EnvFileNotFoundError    — key not found
+│       └── EnvFileKeyExistsError   — add_secret on existing key
+├── BackendNotRegisteredError
+└── ConfigurationError
+```
+
+## Backwards Compatibility
+
+`VaultManager` and `KeyringManager` are aliases for `VaultBackend` and `KeyringBackend` in `__init__.py`. Existing code using the old names continues to work.
+
+## Docs
+
+MkDocs + Material theme. Content at `docs/`. API reference pages in `docs/reference/` are auto-generated from numpy-style docstrings via `mkdocstrings`. Keep docstrings in numpy format when adding or modifying public methods.

credential_bridge-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Muhammad Hassan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.