utic-invocation-settings

Public library for consuming encrypted Unstructured plugin invocation settings — the plugin-side half of the cellular-dataplane "settings in the invoke payload" design. It reads the v1 settings envelope (RSA-OAEP-256-wrapped AES-256-GCM), decrypts inside the plugin at invoke time, and caches only previously authenticated envelopes.

It is deliberately self-contained on cryptography + pydantic — no dependency on any private-feed package — so it can be published to public PyPI and imported by external plugin authors.

Why

Under the cellular dataplane, a shared pod may serve multiple tenants, so a plugin identity decrypts settings routed to that plugin rather than a shared service handing out plaintext. Settings arrive as an opaque ciphertext envelope; this library turns that envelope into a plain settings object, verifying integrity and never logging secrets.

The wire format is frozen in cellular-dataplane/docs/envelope-contract-v1.md. The producer (Secrets Provider / operator) emits exactly that shape; this library is the reference consumer.

Usage

from utic_invocation_settings import extract_envelope, decrypt_settings, TTLCache

_settings_cache = TTLCache(ttl_seconds=300)     # keyed by full-envelope fingerprint
_key_cache = TTLCache(ttl_seconds=3600)         # keyed by recipient + encryption-key digest

def load_private_key(kid: str):
    # Load the RSA private key for this plugin identity's certificate from the mounted secret.
    ...

def on_invoke(body: dict):
    env = extract_envelope(body)
    if env is None:
        return load_legacy_job_settings_file()   # transitional dual-path
    return decrypt_settings(
        env,
        private_key_loader=load_private_key,
        settings_cache=_settings_cache,
        key_cache=_key_cache,
    )

Every failure (unknown format, missing key, RSA/GCM failure, digest mismatch) raises a subclass of InvocationSettingsError — it never returns partial or unverified plaintext.

Security and cache notes

• This is encryption and integrity for the recipient, not producer authentication. A holder of the recipient's public key can create an envelope, so deployments must deliver envelopes over an authenticated control-plane path.
• expires_at and credential_version are plaintext advisory metadata outside the authenticated header. Use them for scheduling/freshness hints, never authorization decisions.
• settings_digest is a public, unsalted SHA-256 value and can link identical settings or support low-entropy guess confirmation. Treat envelopes as sensitive metadata.
• A decrypted-settings cache is keyed by the full authenticated-envelope fingerprint; the AES-key cache is keyed by (kid, encryption_key_digest). clear() is not a revocation barrier for work already decrypting concurrently.

Develop

make install     # uv sync
make test        # unit tests + coverage
make check       # ruff

Note: published to public PyPI on merge to main (see repo README).