agentconfigsafe 0.1.1__py3-none-any.whl

agentconfigsafe-0.1.1.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: agentconfigsafe
+Version: 0.1.1
+Summary: KMS-backed configuration storage for AI agent applications
+Project-URL: Homepage, https://github.com/kiranthakkar/agentsafe
+Project-URL: Repository, https://github.com/kiranthakkar/agentsafe
+Project-URL: Issues, https://github.com/kiranthakkar/agentsafe/issues
+Author: Kiran Thakkar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,configuration,kms,oci,secrets
+Classifier: Development Status :: 3 - Alpha
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: filelock>=3.13
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: oci>=2.100; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: oci
+Requires-Dist: oci>=2.100; extra == 'oci'
+Description-Content-Type: text/markdown
+
+# agentsafe
+
+`agentsafe` stores encrypted configuration values in a project-local `appconfig`
+file. Encryption and decryption are performed by a customer-managed OCI KMS key;
+the file never contains plaintext or key material.
+
+```console
+agentsafe init --profile DEFAULT --compartment <compartment-ocid> \
+  --crypto-endpoint <vault-crypto-url> --key-id <key-ocid>
+agentsafe set OPENAI_API_KEY
+agentsafe get OPENAI_API_KEY
+```
+
+`agentsafe set NAME VALUE` is available for automation, but command-line
+arguments can be exposed in shell history and process listings. Prefer the
+hidden prompt (omit `VALUE`) or pipe the value to standard input.
+
+## Python SDK
+
+Install the OCI provider extra in the application environment:
+
+```console
+python -m pip install "agentconfigsafe[oci]"
+```
+
+Configure the KMS settings once with `agentsafe init` (shown above), or supply
+them directly when constructing `AgentSafe`. The default store is `appconfig`
+in the process's current directory; pass an explicit path when the application
+does not run from its project directory.
+
+```python
+from pathlib import Path
+
+from agentsafe import AgentSafe, KeyNotFoundError
+
+safe = AgentSafe(
+    Path("/srv/my-service/appconfig"),
+    profile="DEFAULT",
+    compartment="ocid1.compartment.oc1..example",
+    crypto_endpoint="https://example-crypto.kms.us-phoenix-1.oraclecloud.com",
+    key_id="ocid1.key.oc1..example",
+)
+
+try:
+    api_key = safe.get("OPENAI_API_KEY")
+except KeyNotFoundError:
+    # Configure the secret before starting the application.
+    raise RuntimeError("OPENAI_API_KEY has not been configured") from None
+
+# Pass ``api_key`` directly to your API client; do not log it or write it to disk.
+```
+
+Settings resolve in this order: constructor arguments, `AGENTSAFE_*`
+environment variables, then `~/.agentsafe/config`. The KMS provider defaults
+to OCI; the OCI profile, compartment OCID, crypto endpoint, and key OCID must
+all be configured. `get()` decrypts only for the duration of the call;
+`list_keys()` returns names without decrypting values.
+
+The PyPI distribution is named `agentconfigsafe`; the Python import and CLI
+remain `agentsafe`.

agentconfigsafe-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+agentsafe/__init__.py,sha256=XcBtNBQqlvPNSrRsGJCnvp44enE1El1FihKs62Y0XNw,279
+agentsafe/cli.py,sha256=LxvpfE64RY3uYWlVZsLG57iizhKQaU8-nBSGnbEsf7Y,2364
+agentsafe/config.py,sha256=30CCbQUfABhzZ81dGpPfGZ6ytTGORdM6y5GmXOrJ9jE,2357
+agentsafe/exceptions.py,sha256=sjQZxaxe7XEULpfBG7jy88Y33UdmazB58Upq0u7RsK8,431
+agentsafe/sdk.py,sha256=nsbjlpgN8lUY7TW2lMkBont2VKtPIKe9AVnfmfgw_zM,3093
+agentsafe/store.py,sha256=ivs3hfIxr0L-5RWirhzAoKZB1ePS7DnixbMAapt0rnA,4365
+agentsafe/kms/__init__.py,sha256=ZnQLL9aGeRCpOLCn5vyEJrFeyTc0RIDP9SwilDF5NKo,1702
+agentsafe/kms/base.py,sha256=AiKKaafYOaZZZGouahpYZeIbho3vhe213dopA_9y3KE,1498
+agentsafe/kms/oci_provider.py,sha256=rtSql42bDwAO7fWNpHdxKct3BJR7klYHY8TkcsPY3RA,3610
+agentconfigsafe-0.1.1.dist-info/METADATA,sha256=2EY5uonOuMqchKsVQTYxmeTFcFzqPHaUj0X7EmLBJiE,3435
+agentconfigsafe-0.1.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agentconfigsafe-0.1.1.dist-info/entry_points.txt,sha256=S3pKY-LQGDKNX-apco6tn21MCTWgZbPE7yT-6XX1tng,120
+agentconfigsafe-0.1.1.dist-info/licenses/LICENSE,sha256=4_6M7TBAKE8rHUfoXkbX-BskUPXTgAMINktJsTB5tdU,1070
+agentconfigsafe-0.1.1.dist-info/RECORD,,

agentconfigsafe-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentconfigsafe-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+agentsafe = agentsafe.cli:app
+
+[agentsafe.kms_providers]
+oci = agentsafe.kms.oci_provider:OCIProvider

agentconfigsafe-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kiran Thakkar
+
+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.

agentsafe/__init__.py

@@ -0,0 +1,12 @@
+"""Public SDK surface for agentsafe."""
+
+from agentsafe.exceptions import AgentSafeError, ConfigError, KeyNotFoundError, KMSError
+from agentsafe.sdk import AgentSafe
+
+__all__ = [
+    "AgentSafe",
+    "AgentSafeError",
+    "ConfigError",
+    "KMSError",
+    "KeyNotFoundError",
+]

agentsafe/cli.py

@@ -0,0 +1,89 @@
+"""Typer command-line interface for agentsafe."""
+
+from pathlib import Path
+
+import typer
+
+from agentsafe.exceptions import AgentSafeError
+from agentsafe.sdk import AgentSafe
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+
+
+def _safe(path: Path, **settings: str | None) -> AgentSafe:
+    return AgentSafe(path, **settings)
+
+
+def _handle(action: object) -> None:
+    try:
+        action()  # type: ignore[operator]
+    except AgentSafeError as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(1) from error
+
+
+@app.command()
+def init(
+    profile: str | None = typer.Option(None),
+    compartment: str | None = typer.Option(None),
+    crypto_endpoint: str | None = typer.Option(None, "--crypto-endpoint"),
+    key_id: str | None = typer.Option(None, "--key-id"),
+    path: Path = typer.Option(Path("appconfig"), "--path"),
+) -> None:
+    """Create global OCI settings and an empty appconfig without overwriting either."""
+    _handle(
+        lambda: AgentSafe.init(
+            path,
+            profile=profile,
+            compartment=compartment,
+            crypto_endpoint=crypto_endpoint,
+            key_id=key_id,
+        )
+    )
+
+
+@app.command()
+def set(
+    key: str,
+    value: str | None = typer.Argument(None),
+    path: Path = typer.Option(Path("appconfig"), "--path"),
+) -> None:
+    """Encrypt and store a value; omit VALUE to enter it through a hidden prompt."""
+    secret = value if value is not None else typer.prompt("Value", hide_input=True)
+    _handle(lambda: _safe(path).set(key, secret))
+
+
+app.command(name="store")(set)
+
+
+@app.command()
+def get(key: str, path: Path = typer.Option(Path("appconfig"), "--path")) -> None:
+    """Decrypt and print one value."""
+
+    def action() -> None:
+        typer.echo(_safe(path).get(key))
+
+    _handle(action)
+
+
+app.command(name="retrieve")(get)
+
+
+@app.command(name="remove")
+def remove(key: str, path: Path = typer.Option(Path("appconfig"), "--path")) -> None:
+    """Remove one value."""
+    _handle(lambda: _safe(path).remove(key))
+
+
+app.command(name="rm")(remove)
+
+
+@app.command(name="list")
+def list_values(path: Path = typer.Option(Path("appconfig"), "--path")) -> None:
+    """List names only; this command never decrypts values."""
+
+    def action() -> None:
+        for key in _safe(path).list_keys():
+            typer.echo(key)
+
+    _handle(action)

agentsafe/config.py

@@ -0,0 +1,62 @@
+"""Resolution and persistence of agentsafe's machine-wide settings."""
+
+import configparser
+import os
+from pathlib import Path
+from typing import Any
+
+from agentsafe.exceptions import ConfigError
+
+CONFIG_PATH = Path.home() / ".agentsafe" / "config"
+ENVIRONMENT_SETTINGS = {
+    "kms_provider": "AGENTSAFE_KMS_PROVIDER",
+    "profile": "AGENTSAFE_PROFILE",
+    "compartment": "AGENTSAFE_COMPARTMENT",
+    "crypto_endpoint": "AGENTSAFE_CRYPTO_ENDPOINT",
+    "key_id": "AGENTSAFE_KEY_ID",
+}
+
+
+def read_config(path: Path = CONFIG_PATH) -> dict[str, str]:
+    """Read settings from the optional INI configuration file."""
+    if not path.exists():
+        return {}
+    parser = configparser.ConfigParser()
+    try:
+        parser.read(path)
+    except (OSError, configparser.Error) as error:
+        raise ConfigError(f"could not read agentsafe configuration at {path}") from error
+    return dict(parser["agentsafe"]) if parser.has_section("agentsafe") else {}
+
+
+def resolve_settings(
+    explicit: dict[str, Any], *, config_path: Path = CONFIG_PATH
+) -> dict[str, Any]:
+    """Resolve settings: explicit, environment, config file, then OCI provider default."""
+    file_settings = read_config(config_path)
+    resolved: dict[str, Any] = {}
+    for key, environment_name in ENVIRONMENT_SETTINGS.items():
+        value = explicit.get(key)
+        if value is None:
+            value = os.environ.get(environment_name)
+        if value is None:
+            value = file_settings.get(key)
+        if value is not None:
+            resolved[key] = value
+    resolved.setdefault("kms_provider", "oci")
+    return resolved
+
+
+def write_config(settings: dict[str, Any], path: Path = CONFIG_PATH) -> None:
+    """Create the global config once, without overwriting an existing file."""
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    parser = configparser.ConfigParser()
+    parser["agentsafe"] = {key: str(value) for key, value in settings.items() if value is not None}
+    try:
+        with path.open("x", encoding="utf-8") as handle:
+            os.chmod(path, 0o600)
+            parser.write(handle)
+    except FileExistsError as error:
+        raise ConfigError(f"agentsafe configuration already exists at {path}") from error
+    except OSError as error:
+        raise ConfigError(f"could not write agentsafe configuration at {path}") from error

agentsafe/exceptions.py

@@ -0,0 +1,17 @@
+"""Typed errors raised by agentsafe."""
+
+
+class AgentSafeError(Exception):
+    """Base class for all agentsafe errors."""
+
+
+class ConfigError(AgentSafeError):
+    """Raised for invalid or missing agentsafe configuration."""
+
+
+class KeyNotFoundError(AgentSafeError):
+    """Raised when a requested configuration name is absent."""
+
+
+class KMSError(AgentSafeError):
+    """Raised when a KMS provider cannot complete an operation."""

agentsafe/kms/__init__.py

@@ -0,0 +1,46 @@
+"""Entry-point discovery and lazy KMS provider construction."""
+
+from collections.abc import Callable
+from importlib import metadata
+from typing import Any, cast
+
+from agentsafe.exceptions import ConfigError
+from agentsafe.kms.base import KMSProvider
+
+ProviderFactory = Callable[..., KMSProvider]
+
+
+def _distribution_name(entry_point: metadata.EntryPoint) -> str:
+    distribution = getattr(entry_point, "dist", None)
+    return distribution.name if distribution is not None else "unknown distribution"
+
+
+def discover_providers() -> dict[str, metadata.EntryPoint]:
+    """Discover provider entry points, rejecting security-sensitive name collisions."""
+    entries = list(metadata.entry_points(group="agentsafe.kms_providers"))
+    providers: dict[str, metadata.EntryPoint] = {}
+    for entry in entries:
+        previous = providers.get(entry.name)
+        if previous is not None:
+            raise ConfigError(
+                f"KMS provider name collision for '{entry.name}': "
+                f"{_distribution_name(previous)} and {_distribution_name(entry)}"
+            )
+        providers[entry.name] = entry
+    return providers
+
+
+def get_provider(name: str, **settings: Any) -> KMSProvider:
+    """Load and instantiate one selected provider without importing others."""
+    entry = discover_providers().get(name)
+    if entry is None:
+        raise ConfigError(f"KMS provider '{name}' is not installed")
+    try:
+        factory = entry.load()
+        return cast(KMSProvider, factory(**settings))
+    except ConfigError:
+        raise
+    except ImportError as error:
+        raise ConfigError(
+            f"provider '{name}' is unavailable; install its optional extra"
+        ) from error

agentsafe/kms/base.py

@@ -0,0 +1,46 @@
+"""Public provider contract."""
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class EncryptedBlob:
+    """A provider-owned ciphertext envelope persisted in ``appconfig``."""
+
+    provider: str
+    ciphertext: str
+    metadata: dict[str, Any]
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "provider": self.provider,
+            "ciphertext": self.ciphertext,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_mapping(cls, value: dict[str, Any]) -> "EncryptedBlob":
+        try:
+            provider = value["provider"]
+            ciphertext = value["ciphertext"]
+            metadata = value["metadata"]
+        except KeyError as error:
+            raise ValueError("ciphertext envelope is missing a required field") from error
+        if (
+            not isinstance(provider, str)
+            or not isinstance(ciphertext, str)
+            or not isinstance(metadata, dict)
+        ):
+            raise TypeError("ciphertext envelope has invalid routing fields")
+        return cls(provider=provider, ciphertext=ciphertext, metadata=metadata)
+
+
+class KMSProvider(Protocol):
+    """A KMS backend that owns encryption and ciphertext interpretation."""
+
+    def encrypt(self, plaintext: str) -> EncryptedBlob:
+        """Encrypt plaintext and return a provider-owned envelope."""
+
+    def decrypt(self, blob: EncryptedBlob) -> str:
+        """Decrypt an envelope created by this provider."""

agentsafe/kms/oci_provider.py

@@ -0,0 +1,88 @@
+"""OCI KMS provider implementation, imported only when OCI is selected."""
+
+from base64 import b64decode, b64encode
+from typing import Any, cast
+
+from agentsafe.exceptions import ConfigError, KMSError
+from agentsafe.kms.base import EncryptedBlob
+
+
+class OCIProvider:
+    """Encrypt and decrypt values through an OCI vault crypto endpoint."""
+
+    def __init__(
+        self,
+        *,
+        profile: str | None = None,
+        compartment: str | None = None,
+        crypto_endpoint: str | None = None,
+        key_id: str | None = None,
+        **_: Any,
+    ) -> None:
+        missing = [
+            label
+            for label, value in {
+                "profile": profile,
+                "compartment": compartment,
+                "crypto_endpoint": crypto_endpoint,
+                "key_id": key_id,
+            }.items()
+            if not value
+        ]
+        if missing:
+            raise ConfigError(f"OCI provider requires: {', '.join(missing)}")
+        try:
+            import oci  # type: ignore[import-untyped]
+        except ImportError as error:
+            raise ConfigError("provider 'oci' requires oci: pip install agentconfigsafe[oci]") from error
+        try:
+            configuration = oci.config.from_file(profile_name=profile)
+            self._client = oci.key_management.KmsCryptoClient(
+                configuration, service_endpoint=crypto_endpoint
+            )
+        except Exception as error:
+            raise KMSError("could not initialize OCI KMS client") from error
+        self._key_id = key_id
+        self._oci: Any = oci
+
+    def encrypt(self, plaintext: str) -> EncryptedBlob:
+        try:
+            details = self._oci.key_management.models.EncryptDataDetails(
+                key_id=self._key_id,
+                plaintext=b64encode(plaintext.encode("utf-8")).decode("ascii"),
+            )
+            response = self._client.encrypt(details).data
+            key_version = getattr(response, "key_version_id", None)
+            metadata = {"key_id": self._key_id}
+            if key_version is not None:
+                metadata["key_version"] = key_version
+            return EncryptedBlob(provider="oci", ciphertext=response.ciphertext, metadata=metadata)
+        except KMSError:
+            raise
+        except Exception as error:
+            raise self._operation_error("encryption", error) from error
+
+    def decrypt(self, blob: EncryptedBlob) -> str:
+        try:
+            key_id = blob.metadata.get("key_id")
+            if not isinstance(key_id, str) or not key_id:
+                raise KMSError("OCI ciphertext envelope is missing key_id metadata")
+            details = self._oci.key_management.models.DecryptDataDetails(
+                ciphertext=blob.ciphertext, key_id=key_id
+            )
+            response = self._client.decrypt(details).data
+            encoded_plaintext = cast(str, response.plaintext)
+            return b64decode(encoded_plaintext, validate=True).decode("utf-8")
+        except KMSError:
+            raise
+        except Exception as error:
+            raise self._operation_error("decryption", error) from error
+
+    @staticmethod
+    def _operation_error(operation: str, error: Exception) -> KMSError:
+        """Expose only safe OCI diagnostics; request text may contain a secret."""
+        status = getattr(error, "status", None)
+        code = getattr(error, "code", None)
+        if isinstance(status, int) and isinstance(code, str):
+            return KMSError(f"OCI KMS {operation} failed (HTTP {status}, {code})")
+        return KMSError(f"OCI KMS {operation} failed ({type(error).__name__})")

agentsafe/sdk.py

@@ -0,0 +1,77 @@
+"""User-facing AgentSafe SDK."""
+
+from pathlib import Path
+from typing import Any
+
+from agentsafe.config import CONFIG_PATH, resolve_settings, write_config
+from agentsafe.exceptions import ConfigError
+from agentsafe.kms import get_provider
+from agentsafe.kms.base import KMSProvider
+from agentsafe.store import ConfigStore
+
+
+class AgentSafe:
+    """Store and retrieve string configuration values encrypted by a KMS provider."""
+
+    def __init__(self, appconfig_path: Path | str = "appconfig", **settings: Any) -> None:
+        """Create a client using explicit settings, environment, then global configuration."""
+        self.settings = resolve_settings(settings)
+        self.store = ConfigStore(appconfig_path)
+
+    @classmethod
+    def init(
+        cls,
+        appconfig_path: Path | str = "appconfig",
+        *,
+        config_path: Path = CONFIG_PATH,
+        **settings: Any,
+    ) -> "AgentSafe":
+        """Create global settings and an empty project store without overwriting either."""
+        resolved = resolve_settings(settings, config_path=config_path)
+        provider = resolved.get("kms_provider", "oci")
+        if provider == "oci":
+            missing = [
+                key
+                for key in ("profile", "compartment", "crypto_endpoint", "key_id")
+                if not resolved.get(key)
+            ]
+            if missing:
+                raise ConfigError(f"OCI configuration requires: {', '.join(missing)}")
+        store = ConfigStore(appconfig_path)
+        if config_path.exists() or store.path.exists():
+            target = config_path if config_path.exists() else store.path
+            raise ConfigError(f"init refused to overwrite existing file: {target}")
+        write_config(resolved, config_path)
+        store.initialize()
+        return cls(appconfig_path, **resolved)
+
+    def set(self, key: str, value: str) -> None:
+        """Encrypt and store a string value under a non-empty configuration name."""
+        self._validate_key(key)
+        if not isinstance(value, str):
+            raise ConfigError("configuration values must be strings")
+        provider = self._provider()
+        self.store.set(key, provider.encrypt(value))
+
+    def get(self, key: str) -> str:
+        """Decrypt and return one configuration value; absent names raise KeyNotFoundError."""
+        self._validate_key(key)
+        blob = self.store.get(key)
+        return self._provider(blob.provider).decrypt(blob)
+
+    def remove(self, key: str) -> None:
+        """Remove one encrypted configuration value."""
+        self._validate_key(key)
+        self.store.remove(key)
+
+    def list_keys(self) -> list[str]:
+        """Return configuration names without decrypting any value."""
+        return self.store.list_keys()
+
+    def _provider(self, name: str | None = None) -> KMSProvider:
+        return get_provider(name or self.settings["kms_provider"], **self.settings)
+
+    @staticmethod
+    def _validate_key(key: str) -> None:
+        if not isinstance(key, str) or not key:
+            raise ConfigError("configuration name must be a non-empty string")

agentsafe/store.py

@@ -0,0 +1,112 @@
+"""Durable, locked access to the project-local ciphertext store."""
+
+import json
+import os
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from filelock import FileLock
+
+from agentsafe.exceptions import ConfigError, KeyNotFoundError
+from agentsafe.kms.base import EncryptedBlob
+
+SCHEMA_VERSION = 1
+
+
+class ConfigStore:
+    """The JSON ``appconfig`` file; it contains ciphertext envelopes only."""
+
+    def __init__(self, path: Path | str = "appconfig") -> None:
+        self.path = Path(path)
+        self.lock_path = Path(f"{self.path}.lock")
+
+    def initialize(self) -> None:
+        """Create an empty store and fail safely if it already exists."""
+        self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        try:
+            with self.path.open("x", encoding="utf-8") as handle:
+                os.chmod(self.path, 0o600)
+                json.dump({"schema_version": SCHEMA_VERSION, "entries": {}}, handle)
+        except FileExistsError as error:
+            raise ConfigError(f"appconfig already exists at {self.path}") from error
+        except OSError as error:
+            raise ConfigError(f"could not create appconfig at {self.path}") from error
+
+    def list_keys(self) -> list[str]:
+        return list(self._read_entries().keys())
+
+    def get(self, key: str) -> EncryptedBlob:
+        entries = self._read_entries()
+        try:
+            raw = entries[key]
+        except KeyError as error:
+            raise KeyNotFoundError(f"no configuration value named '{key}'") from error
+        if not isinstance(raw, dict):
+            raise ConfigError("stored ciphertext envelope cannot be read")
+        try:
+            return EncryptedBlob.from_mapping(raw)
+        except (TypeError, ValueError) as error:
+            raise ConfigError("stored ciphertext envelope cannot be routed") from error
+
+    def set(self, key: str, blob: EncryptedBlob) -> None:
+        with self._lock():
+            entries = self._read_entries()
+            entries[key] = blob.to_mapping()
+            self._write_entries(entries)
+
+    def remove(self, key: str) -> None:
+        with self._lock():
+            entries = self._read_entries()
+            if key not in entries:
+                raise KeyNotFoundError(f"no configuration value named '{key}'")
+            del entries[key]
+            self._write_entries(entries)
+
+    @contextmanager
+    def _lock(self) -> Iterator[None]:
+        lock = FileLock(str(self.lock_path))
+        with lock:
+            # filelock creates this lazily; chmod after acquisition covers supported POSIX systems.
+            try:
+                os.chmod(self.lock_path, 0o600)
+            except OSError:
+                pass
+            yield
+
+    def _read_entries(self) -> dict[str, Any]:
+        try:
+            with self.path.open(encoding="utf-8") as handle:
+                document = json.load(handle)
+        except FileNotFoundError as error:
+            raise ConfigError(f"appconfig does not exist at {self.path}") from error
+        except (OSError, json.JSONDecodeError) as error:
+            raise ConfigError(f"could not read appconfig at {self.path}") from error
+        if not isinstance(document, dict):
+            raise ConfigError("appconfig root must be a JSON object")
+        entries = document.get("entries", {})
+        if not isinstance(entries, dict):
+            raise ConfigError("appconfig entries must be a JSON object")
+        return entries
+
+    def _write_entries(self, entries: dict[str, Any]) -> None:
+        descriptor, temp_name = tempfile.mkstemp(
+            prefix=".appconfig-", dir=self.path.parent, text=True
+        )
+        try:
+            os.fchmod(descriptor, 0o600)
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                json.dump({"schema_version": SCHEMA_VERSION, "entries": entries}, handle, indent=2)
+                handle.write("\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temp_name, self.path)
+            os.chmod(self.path, 0o600)
+        except OSError as error:
+            try:
+                os.unlink(temp_name)
+            except FileNotFoundError:
+                pass
+            raise ConfigError(f"could not write appconfig at {self.path}") from error