gemstone_utils.experimental.secrets_resolver

Experimental. API and behavior may change; see Experimental secrets resolver for usage guidance.

Experimental secret reference resolver for configuration bootstrap.

exception gemstone_utils.experimental.secrets_resolver.BackendNotImplemented(prefix, message, *, reason)

Bases: RuntimeError

Reference uses a removed or unregistered backend prefix.

Variables:

• prefix – Normalized backend name from the reference.

• reason – "removed" or "unregistered".

Parameters:

• prefix (str)

• message (str)

• reason (str)

Return type:

None

exception gemstone_utils.experimental.secrets_resolver.FilePathNotAllowed(path, allowed_prefixes)

Bases: ValueError

A file: path is outside the configured allowlist.

Variables:

• path – Resolved path string that was rejected.

• allowed_prefixes – Effective allowlist prefix strings.

Parameters:

• path (str)

• allowed_prefixes (frozenset[str])

Return type:

None

gemstone_utils.experimental.secrets_resolver.allowed_file_path_prefixes()

Return resolved absolute prefix strings for the file: allowlist.

Returns:

Frozenset of allowed prefix path strings (POSIX form).

Return type:

frozenset[str]

gemstone_utils.experimental.secrets_resolver.is_backend_registered(prefix)

Return whether a backend prefix is registered.

Parameters:

prefix (str) – Backend name without trailing colon.

Returns:

True if registered.

Return type:

bool

gemstone_utils.experimental.secrets_resolver.list_backends()

Return sorted registered backend prefix names.

Returns:

List of normalized backend names (without colons).

Return type:

list[str]

gemstone_utils.experimental.secrets_resolver.register_backend(prefix, resolver, *, replace=False)

Register a pluggable backend for a reference prefix.

Built-in backends env, file, secret, and literal are pre-registered. Use literal: for opaque values containing colons.

Parameters:

• prefix (str) – Backend name without trailing colon (case-insensitive).

• resolver (Callable[[str], str | None]) – Callable (body: str) -> str | None; None skips post-processing.

• replace (bool) – Allow replacing an existing registration when True.

Raises:

ValueError – If prefix is empty or already registered (and not replace).

Return type:

None

gemstone_utils.experimental.secrets_resolver.resolve_env(varname)

Parameters:

varname (str)

Return type:

str

gemstone_utils.experimental.secrets_resolver.resolve_file(path)

Parameters:

path (str)

Return type:

str

gemstone_utils.experimental.secrets_resolver.resolve_literal(body)

Parameters:

body (str)

Return type:

str

gemstone_utils.experimental.secrets_resolver.resolve_secret(value)

Resolve a secret reference string to its plaintext value.

Supported forms:

• env:VAR — environment variable (cached, then scrubbed)

• file:/absolute/path — UTF-8 file under allowlist

• secret:name — container secret mount

• literal:opaque — substring after first colon unchanged

• Registered backends via register_backend()

• Encrypted-field wire strings (requires set_keyctx_resolver())

• Plain strings without : returned unchanged

Parameters:

value (str) – Reference string or plaintext.

Returns:

Resolved secret string.

Raises:

• BackendNotImplemented – Unknown or removed prefix.

• FilePathNotAllowed – file: path outside allowlist.

• KeyError, FileNotFoundError, ValueError – Backend-specific failures.

Return type:

str

gemstone_utils.experimental.secrets_resolver.resolve_secretfile(name)

Parameters:

name (str)

Return type:

str

gemstone_utils.experimental.secrets_resolver.set_allowed_file_path_prefixes(prefixes)

Replace the file: path allowlist entirely.

Until called, only paths under /app/secret are allowed. Prefixes must be absolute; ~ is rejected. Bare /etc or filesystem root logs a warning but is not blocked.

Parameters:

prefixes (Sequence[str | PathLike[str]]) – Absolute directory prefixes permitted for file: reads.

Return type:

None

gemstone_utils.experimental.secrets_resolver.set_keyctx_resolver(func)

Register resolver for encrypted wire values in secret strings.

Required before resolving values that match is_encrypted_prefix. Separate from EncryptedString.set_keyctx_resolver.

Parameters:

func (Callable[[str], KeyContext]) – Callable (keyid: str) -> KeyContext.

Return type:

None

gemstone_utils.experimental.secrets_resolver.unregister_backend(prefix)

Remove a registered backend prefix.

Parameters:

prefix (str) – Backend name without trailing colon.

Return type:

None