cayu.vaults.redaction

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

contains_redacted_secret

from cayu.vaults import contains_redacted_secret

Return whether JSON-compatible data contains the durable redaction marker.

contains_redacted_secret(value: Any) -> bool

Release source · Runtime guarantees · Capability guides

REDACTED_SECRET

from cayu.vaults import REDACTED_SECRET

REDACTED_SECRET = '[REDACTED_SECRET]'

Release source · Runtime guarantees · Capability guides

SecretRedactionCapacityError

from cayu.vaults import SecretRedactionCapacityError

Raised before unresolved streaming-redaction state exceeds its bound.

Bases: RuntimeError.

init (method)

SecretRedactionCapacityError.__init__(*, released: bytes=b'') -> None

Release source · Runtime guarantees · Capability guides

SecretRedactionStream

from cayu.vaults import SecretRedactionStream

Redact registered secrets before releasing ordered byte fragments.

A suffix that may begin either a secret or the public marker remains private until a later fragment makes it decidable. Callers must distinguish a proven normal EOF from uncertain abandonment: finish_complete may release an unmatched suffix, while abort discards it.

init (method)

SecretRedactionStream.__init__(redactor: SecretRedactor, *, max_retained_bytes: int | None=None) -> None

feed (method)

SecretRedactionStream.feed(chunk: bytes) -> bytes

finish_complete (method)

SecretRedactionStream.finish_complete() -> bytes

Finish after proven EOF and release the final unmatched suffix.

abort (method)

SecretRedactionStream.abort() -> bool

Seal an incomplete stream and report whether raw bytes were discarded.

Release source · Runtime guarantees · Capability guides

SecretRedactionTail

from cayu.vaults import SecretRedactionTail

Retain a marker-safe bounded tail from an incrementally redacted source.

init (method)

SecretRedactionTail.__init__(redactor: SecretRedactor, *, max_bytes: int) -> None

feed (method)

SecretRedactionTail.feed(chunk: bytes) -> None

finish_complete (method)

SecretRedactionTail.finish_complete() -> None

abort (method)

SecretRedactionTail.abort() -> None

text (method)

SecretRedactionTail.text() -> str

Release source · Runtime guarantees · Capability guides

SecretRedactor

from cayu.vaults import SecretRedactor

Redacts known resolved secret values from strings and JSON-like data.

init (method)

SecretRedactor.__init__(secrets: str | SecretStr | ResolvedSecret | Sequence[str | SecretStr | ResolvedSecret] | None=None) -> None

has_values (property)

SecretRedactor.has_values() -> bool

max_secret_utf8_bytes (property)

SecretRedactor.max_secret_utf8_bytes() -> int

Return the bounded overlap needed to redact across a byte boundary.

pagination_overlap_utf8_bytes (property)

SecretRedactor.pagination_overlap_utf8_bytes() -> int

Return source overlap needed for source-position-aware page redaction.

with_secret (method)

SecretRedactor.with_secret(secret: str | SecretStr | ResolvedSecret) -> SecretRedactor

merged_with (method)

SecretRedactor.merged_with(other: SecretRedactor) -> SecretRedactor

Combine two registries without exposing either registry’s values.

with_python_repr_forms (method)

SecretRedactor.with_python_repr_forms() -> SecretRedactor

Also match each secret in the escaped forms Python text commonly uses.

Exception messages quote values with repr (an OSError filename, a KeyError key, f"{path!r}" inside another repr), ascii, repr of the UTF-8 bytes, or json.dumps. Each form turns a newline into \n, a backslash into \\ and so on. Forms equal to the secret itself are not added.

redact_cut_text (method)

SecretRedactor.redact_cut_text(value: str, *, cut_head: bool=False, cut_tail: bool=False) -> str

Redact text cut from a longer source, dropping what a cut may have split.

Everything that starts within the longest secret’s length of a cut edge is discarded, redactions included, by position in value. A secret split by the cut, and any shorter secret nested inside it, therefore leave no visible remainder.

has_same_registry (method)

SecretRedactor.has_same_registry(other: SecretRedactor) -> bool

Compare registries without exposing their secret values.

is_exact_secret (method)

SecretRedactor.is_exact_secret(value: str) -> bool

Return whether value exactly equals one registered secret.

contains_secret_bytes (method)

SecretRedactor.contains_secret_bytes(value: bytes) -> bool

Return whether raw bytes contain any registered non-marker secret.

redact_uppercase_text (method)

SecretRedactor.redact_uppercase_text(value: str) -> str

Redact text against uppercase-normalized registered secret values.

redact_stripped_text (method)

SecretRedactor.redact_stripped_text(value: str) -> str

Redact text against whitespace-trimmed registered secret values.

redact_text (method)

SecretRedactor.redact_text(value: str) -> str

redact_text_bounded (method)

SecretRedactor.redact_text_bounded(value: str, *, max_bytes: int) -> str

Redact a diagnostic string before applying its UTF-8 byte bound.

redact_text_bounded_with_marker (method)

SecretRedactor.redact_text_bounded_with_marker(value: str, *, max_bytes: int, truncation_marker: str) -> tuple[str, bool]

Redact complete text, then append an atomic marker when it is shortened.

redact_text_head (method)

SecretRedactor.redact_text_head(value: str, *, max_bytes: int) -> tuple[str, bool]

Redact a complete string, then return its marker-safe bounded head.

redact_utf8_head (method)

SecretRedactor.redact_utf8_head(value: bytes, *, max_bytes: int, source_complete: bool) -> tuple[str, bool]

Project a possibly incomplete UTF-8 source prefix without exposing its suffix.

source_complete=False means the caller did not observe authoritative EOF. The streaming redactor therefore discards every suffix whose safety could depend on unavailable bytes instead of treating the captured prefix as a complete value. Bytes buffered by the incremental UTF-8 decoder are likewise withheld and reported as truncation.

redact_bytes_head (method)

SecretRedactor.redact_bytes_head(value: bytes, *, max_bytes: int, source_complete: bool) -> tuple[bytes, bool]

Project a possibly incomplete binary prefix without exposing its suffix.

redact_utf8_page (method)

SecretRedactor.redact_utf8_page(value: bytes, *, window_offset: int, page_offset: int, page_end: int, max_bytes: int, source_complete: bool) -> tuple[str, bool]

Project one raw-source page without exposing cross-page secret fragments.

redact_utf8_page_with_progress (method)

SecretRedactor.redact_utf8_page_with_progress(value: bytes, *, window_offset: int, page_offset: int, page_end: int, total_bytes: int, max_bytes: int) -> tuple[str, int]

Return a framed text page and the exact next stored-byte position.

Unlike prefix capture, this operation requires lookbehind and lookahead proving the page’s redaction context. It never splits an atomic redaction span or advances past output omitted by the byte bound. A source span or replacement that cannot fit raises ValueError rather than losing text.

redact_bytes_page (method)

SecretRedactor.redact_bytes_page(value: bytes, *, window_offset: int, page_offset: int, page_end: int, max_bytes: int, source_complete: bool) -> tuple[bytes, bool]

Project one raw-source byte page without exposing cross-page fragments.

stream_bytes (method)

SecretRedactor.stream_bytes(*, max_retained_bytes: int | None=None) -> SecretRedactionStream

Create an ordered byte-stream redactor for this registry.

max_retained_bytes bounds source bytes whose final redaction is still dependent on future input. Exceeding the bound fails closed before the unresolved source is published.

redact_json (method)

SecretRedactor.redact_json(value: Any) -> Any

redact_json_values (method)

SecretRedactor.redact_json_values(value: Any, *, preserve_string_fields: Collection[str]=()) -> Any

Redact JSON string values without rewriting protocol object keys.

require_no_secret_keys (method)

SecretRedactor.require_no_secret_keys(value: Any, *, field_name: str='value', preserve_keys: Collection[str]=(), untrusted_container_keys: Collection[str]=(), match_short_substrings: bool=False) -> None

Fail closed when a known secret occurs in an untyped JSON object key.

Release source · Runtime guarantees · Capability guides