gemstone_utils

gemstone_utils provides cryptographic helpers, transparent AES-GCM encrypted SQLAlchemy fields, and a minimal experimental secrets resolver suitable for Pydantic’s BeforeValidator. It is designed for applications that need reversible secret storage with minimal plaintext exposure and predictable operational behavior.

The package is licensed under the MPL-2.0, allowing use in both open-source and proprietary projects while keeping modifications to this library itself open.

User guide

User guide

• Public API guide
  • Documentation map
  • Typical bootstrap order
  • Cryptography and encrypted fields
  • Key management
  • SQLAlchemy encrypted columns
  • SQL key storage
  • Database layer
  • Leader election
  • Experimental secrets resolver
  • API reference
• SQLAlchemy encrypted columns
  • What EncryptedString does
  • Initialization order
  • Key ids are strings (UUIDs)
  • Rotation behavior
  • Failure modes
  • Related modules
• SQL key storage (sqlalchemy.key_storage)
  • Two meanings of “key id” in wire strings
  • Tables
  • Bootstrap (new database)
  • make_keyctx_resolver
  • rewrap_key_records
  • Key ids and wire format
  • Backup and recovery
  • Common mistakes
• SQL-backed leader election (gemstone_utils.election)
  • Concepts
  • Schema
  • Typical application loop
  • Protocol rules
  • Implementation notes
  • Public API
• Experimental secrets resolver
  • Schemes
  • Path security
  • BackendNotImplemented
  • Encrypted wire values ($A256GCM$...)
  • API notes
  • Operational caveats

Release notes

Release notes

• gemstone_utils release notes
  • Pre-release naming (gemstone_utils)
  • Unreleased
  • v0.5.0a1 (alpha)
  • v0.4.1
  • v0.4.0 (stable)
  • v0.4.0rc1 (release candidate)
  • v0.3.0a2 (alpha)
  • v0.3.0a1 (alpha)
  • v0.2.1
  • v0.2.0
  • v0.1.0

API reference

Per-module symbol documentation generated from Google-style docstrings. For integration patterns and bootstrap order, see Public API guide.

API reference

• API reference
  • gemstone_utils.crypto
  • gemstone_utils.key_id
  • gemstone_utils.types
  • gemstone_utils.encrypted_fields
  • gemstone_utils.key_mgmt
  • gemstone_utils.key_mgmt.registry
  • gemstone_utils.key_mgmt.kdf
  • gemstone_utils.db
  • gemstone_utils.election
  • gemstone_utils.sqlalchemy.encrypted_type
  • gemstone_utils.sqlalchemy.lazy_secret
  • gemstone_utils.sqlalchemy.key_storage
  • gemstone_utils.experimental.secrets_resolver

Quick links

Topic	Guide
SQLAlchemy EncryptedString, init order, rotation	SQLAlchemy encrypted columns
Persisted keys (key_storage), bootstrap	SQL key storage (sqlalchemy.key_storage)
SQL-backed leader election	SQL-backed leader election (gemstone_utils.election)
Experimental resolve_secret and backends	Experimental secrets resolver
Curated public API (stable vs experimental)	Public API guide
Breaking changes and migration	gemstone_utils release notes

Install from PyPI:

pip install gemstone_utils

Source: github.com/gemstone-software-dev/gemstone_utils